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Introduction 



Welcome to Turbo Pascal for the Mac. The programming language Turbo Pascal 
is designed to meet the needs of all types of Macintosh users: It's a structured, 
high-level language that can be used to write programs for almost any 
application. 

This manual walks novice programmers through writing, compiling, and sav- 
ing Turbo Pascal programs. It also teaches you how to take existing Pascal pro- 
grams and run them under Turbo Pascal. 

Sample programs are provided on your distribution disks for you to study and 
practice on. You can also tailor these sample exercises to your particular needs. 

You should be somewhat familiar with the basics of operating a Macintosh 
before you start this manual. That is, you should know about clicking on icons, 
using the mouse, opening folders, and other Macintosh features. If you're not 
comfortable with these terms, spend some time playing with your Mac and using 
your Macintosh's user's guide. You may also want to skim through the glossary at 
the end of this manual to get some understanding of the concepts we've used. 



The Manual 



This manual is divided into three main sections: the Users Guide (Part I), the 
Reference Section (Part II), and the Appendices, A glossary and index round out 
the manual. 

The Users Guide introduces you to Turbo Pascal, shows you how to use it, and 
includes chapters that focus on such specific features as units, desk accessories, 
and debugging. Here's a breakdown of the chapters: 

Chapter I: Setting Up shows you how to set up your Mac for Turbo Pascal, 
describes the files on your distribution disk, and explains how to make backup 
disks. 

Chapter 2: Getting Started with Turbo Pascal leads you directly from loading 
Turbo Pascal into writing simple programs. It then suggests how you should go 
about reading the rest of the manual, depending on your familiarity with the Mac 
and with Pascal. 

Chapter 3: Using the Editor explains Turbo Pascal's menus (except for the Com- 
pile menu, covered in the next chapter) and shows you how to use the editor to 
open, edit, change, and save files. 

Chapter 4: Using the Compiler describes how to implement the programs you 
learned to create in Chapter 3, using the compiler. It also shows you common 
programming errors and how to avoid them. 

Chapter 5: Writing Textbook Pascal Programs shows you how to take standard 
Pascal programs and use them with Turbo Pascal without having to know any- 
thing about the Macintosh Toolbox and operating system. 

Chapter 6: Harnessing the Full Power of Your Mac is a quick guide to the 
Macintosh and the tools that exist to help you write more complex programs. 

Chapter 7: Units and Other Mysteries tells you what a unit is, how it's used, 
and what predefined units (libraries) Turbo Pascal provides. 

Chapter 8: Writing Your Own Units goes into the general structure of a unit and 
its interface and implementation portions. It shows you how to initialize and 
compile a unit. 

Chapter 9: Writing Your Own Macintosh Applications shows you how to put 

together your own Mac-style programs, complete with menus, windows, and 

cursors = 

Chapter 10: Graduation: Writing a Desk Accessory tells you all you need to 
know to design and write desk accessory programs. 
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Chapter U: UNITMOVER, Chapter 12: RMAKER, and Chapter 13: FONT/DA 
MOVER give detailed instructions on these utilities, which come on your Turbo 
Pascal disks. 

Chapter 14: Debugging Your Turbo Pascal Program explains how to use 
MACSBUG to check for errors in your program. 

Chapter 15: The Turbo Pascal Menu Reference is a complete guide to the menu 
commands in Turbo Pascal. 

Now we move on to the Reference Section of the manual. The first 11 chapters 
offer technical information on the following features: 

Chapter 16: Tokens and Constants 

Chapter 17: Blocks, Locality, and Scope 

Chapter 18: Types 

Chapter 19: Variables 

Chapter 20: Expressions 

Chapter 21: Statements 

Chapter 22: Procedures and Functions 

Chapter 23: Programs and Units 

Chapter 24: Input and Output 

Chapter 25: Standard Procedures and Functions 

Chapter 26: The Standard Apple Numeric Environment (SANE) Library 

Chapter 27: Inside Turbo Pascal offers additional technical information for 
advanced Pascal programmers, including internal data formats, assembly-lan- 
guage interfaces, and user-defined device drivers. 

Finally, there are six appendices in the manual: 

Appendix A: Comparing Turbo Pascal with Other Pascals 
Appendix B: Error Messages and Codes 
Appendix C: Compiler Directives 
Appendix D: Macintosh Interface Units 
Appendix E: Macintosh Character Set 

Appendix F: TURTLEGRAPHICS: Mac Graphics Made Easier 



Typography 



The use of italic and boldface type in this manual follows certain conventions. 
Reserved words are set in lowercase, boldface type. Constant identifiers, field 
identifiers, and formal parameter identifiers are italicized when referred to 
within text. Other identifiers — unit and program names, labels, types, variables, 
procedures, and functions — ^begin with an uppercase letter; they also are itali- 
cized when referred to within text. 
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The command key (the cloverleaf key on the Mac keyboard) is represented by 
the keycap (3- 

Pascal syntax is illustrated by diagrams. To follow a syntax diagram, start at the 
top left and follow the arrows through the diagram. Alternative paths are often 
possible; paths that begin at the left and end with an arrowhead on the right are 
valid paths. A path traverses boxes that hold the names of elements that are used 
to construct that portion of the syntax. 

The names in rectangular boxes stand for actual constructions. Those in circu- 
lar boxes — ^reserved words, operators, and punctuation — ^are the actual terms 
that should be used in the program. 
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How to Contact Borland 



If, after reading this manual and using Turbo Pascal, you would like to contact 
Borland with comments or suggestions, we suggest the following procedures. 

The best way is to log on to Borland's forum on CompuServe: Type GO BOR 
from the main CompuServe menu and follow the menus to section 4. Leave your 
questions or comments here for the support staflF to process. 

If you prefer, write a letter describing your comments in detail and send it to 
the Technical Support Department, Borland International, 4585 Scotts Valley 
Drive, Scotts Valley, CA 95066, USA. 

As a last resort, you can telephone our Technical Support department. If 
you're calling with a problem, please have the following information handy 
before you call: 

• Product name and version number 

• Computer make and model number 

• Operating system and version number 
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Users Guide 



CHAPTER 



Setting Up 



Before you actually begin using Turbo Pascal, you should make a backup copy of 
your disks so that you can put your master disks in a safe place. This chapter tells 
you how to do that. It also describes the files on your Turbo Pascal disks so that 
you can see what files are provided and which you'll need. 

Before you go on, you should have some familiarity with the Mac. You should 
know how to turn your Mac on and oflF, how to move the mouse around, how to 
select commands from a menu, how to manipulate (move, resize, and close) 
windows with the mouse, and how to select and launch applications. If you have 
questions about using the Mac, please refer to your Macintosh owner's manual. 

Making Working Copies 



Borland's philosophy — selling software without copy protection — is based on 
trust. As it says in the license statement at the beginning of this manual, you are 
authorized to make working copies of the distribution disks. You can then put the 
originals in a safe place. 

Here's how to copy your Turbo Pascal and Utilities & Sample Programs disks. 

First, with the Macintosh off, put your Turbo Pascal disk in the internal disk 
drive and turn the Mac on. The Mac boots up and displays a window with the 
contents of your Turbo Pascal disk. 
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Second, insert a blank disk, or a disk that doesn't contain anything you want to 
save, in your external disk drive. (If you don't have one, we'll tell you what to do 
in a few paragraphs.) If you Ve inserted a new disk or one that's been used with 
some other computer system, the Mac asks if you want to initialize it. If it is in a 
double-sided disk drive, you have the option of formatting it as single- or double- 
sided; it's best to choose whichever corresponds to your internal disk drive. 
Remember, initiaUzing erases all existing files on the disk. When initialization is 
done, you'll be asked to name the disk; give it something hke ''TP Mac," 

Third, point to the Turbo Pascal disk icon, press the mouse button, and hold it 
down. Now drag that icon to the icon of your work disk. That disk's icon should 
now turn dark. Release the mouse button. You'll now get a dialog box that asks if 
you really want to replace the contents of the disk in your external drive with the 
contents of the disk in your internal drive. Point to OK and press the mouse 
button. All the files on your Turbo Pascal master disk will be copied over to your 
work disk. 

Fourth, eject both disks: Click on the disk icon, then select Eject from the File 
menu, or press QCO- Label your new working copy of Turbo Pascal, and store 
your Turbo Pascal master disk somewhere safe. Turn your Mac off, place your 
working disk into the internal disk drive, and turn the Mac back on. You now 
have a working copy of Turbo Pascal. 

Repeat with the Utilities & Sample Programs disk. 
What If I Only Have One Disk Drive? 



Prepare yourself for some disk swapping. Boot up with your Turbo Pascal master 
disk, as described above, then eject it. 

Insert your blank work disk. If necessary, initialize it as described above. You 
should now have two disk icons on your desktop (Macintosh screen). 

Drag the icon for the Turbo Pascal master disk onto the icon of your work disk. 
You're asked to reinsert the Turbo Pascal master disk; do so. At the ''Replace all 
this?" prompt, click the OK button. 

The actual copying now takes place. You'll be asked to swap disks from time to 
time, so that your Mac can read from the master disk and write to the destination 
disk. The actual number of swaps depends upon the size of your disk drive and 
the amount of memory in your Mac. 

Repeat this procedure with the Utilities & Saniple Programs disk. 
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what If Vm Using a Hard Disk? 



Copy all the files and folders (except for the SYSTEM FOLDER) from your 
Turbo Pascal master disks to any volume or subdirectory on your hard disk. Store 
the masters. 

Bypassing the Desktop 



If your working copy of Turbo Pascal is a bootable disk (that is, if it is the disk you 
boot from when you turn your Macintosh on), you can make Turbo Pascal your 
startup application. This means that when you boot from your Turbo Pascal work 
disk, instead of having to wait for the desktop to come up and then double- 
chcking on the Turbo icon, you will automatically go into Turbo Pascal. 

To do this, boot up using your Turbo Pascal work disk. Click once on the Turbo 
icon, so that it becomes dark but doesn't start executing. Go to the Special menu 
and select Set Startup. A dialog box comes up, asking you to verify that you want 
Turbo to be the startup application. Select the OK button. 

From now on, when you boot up using that disk, you'll bypass the desktop and 
go immediately into Turbo Pascal. 

The FUes on the Disks 



Your Turbo Pascal master disks have quite a few files and folders (which contain 
more files). Unlike the other Pascal programs, however. Turbo Pascal can run on 
only the TURBO file. This simplicity makes Turbo Pascal easy to use and conser- 
vative of your memory space. However, it doesn't skimp on options. 

Here's a quick rundown of the files, with descriptions showing what each file 
provides. The TURBO and SYSTEM FOLDER files are on the Turbo Pascal 
disk; all other files are on the Utilities & Sample Programs disk. 
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Table 1-1 Files on Your Distribution Disk 



TURBO The Turbo Pascal compiler/editor. This file also contains 

the Pascal run- time and Mac interface units. You 
definitely need it. 

SYSTEM FOLDER A folder containing the system files: 

SYSTEM The Macintosh operating system. This file also holds 

system resources, such as fonts and desk accessories. Your 
disk has only a limited number of these to conserve space. 
Essential if you are going to boot up using your Turbo 
Pascal work disk. 

FINDER The Macintosh user interface program. This is what 

brings up the desktop, allows you to select and run a 
program, and so on. Also essential if you plan to boot 
from your work disk. 

IMAGEWRITER The printer driver for the Imagewriter printer. You need 

this if you're going to print anything, either from within 
Turbo Pascal or within your own program. 

UTILITIES This folder contains UNITMOVER, RMAKER, 

FONT/DA MOVER, MACSBUG, MACINTALK, and 
APPLETALK: 

UNITMOVER Utility for moving units (libraries) in and out of Turbo 

Pascal. You don't need it unless you write your own 
units and store them in Turbo Pascal. 

RMAKER The Resource Maker. This converts resource source files 

(.R) into resource data files (.RSRC), which can then be 
used by your programs. If youVe writing Mac-style 
programs, youll need this file. 

FONT/DA MOVER Utility for moving fonts and desk accessories in and out 

of your SYSTEM file. You need it if you plan to write 
desk accessories. 

MACSBUG A debugger, that is, a program that helps you to track 

down and correct errors in your program. This is for 
more sophisticated users; after reading about it in 
Chapter 14, you can decide whether to include it. 

MACINTALK A resource file for speech synthesis. You'll need it to use 

the MacinTalk unit in any of your programs. 

ATALK/ABPACKAGE A resource file for using the APPLETALK network. 

You'll need it to use the APPLETALK unit in any of 
your programs. 

SAMPLE PROGRAMS This folder contains sample programs, including: 
MYDEMO.PAS A sample program that shows how to write Mac-style 

programs. Brings up a window and its own menu bar; 
allows you to run several different benchmarks 
(graphics, I/O, etc.); supports desk accessories. 
MYDEMO.R A resource file for MYDEMO.PAS. You must run 

RMAKER on it (producing MYDEMO.RSRC) before 
you can compile and run MYDEMO.PAS. 
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Table 1-1 Files on Your Distribution Disks y continued 



MYDA.PAS 


A sample desk accessory whose code illustrates all the 




diflPerent events that you might need to handle in a desk 




accessory. 


MYDA.INC 


An include file for MYDA.PAS; it contains most of the 




event-handling routines. 


MYDA.R 


A resource file for MYDA.PAS. You must run RMAKER 




on it (to produce MYDA.RSRC) before you can compile 




MYDA.PAS. 



What If I DoYit Want to Use Turbo Pascal's System Files? 



Format a blank disk and copy onto it the system files you want to use. Boot up 
using it. Put the Turbo Pascal master disk in your external drive. Copy to your 
system disk all its files and folders, except for the one labeled SYSTEM 
FOLDER. 

Eject the Turbo Pascal master disk and put it somewhere safe. 
What If I DoYit Want All the Turbo Pascal Files? 



Make copies of the Turbo Pascal master disks, using one of the methods 
described previously. Throw away (that is, move into the Trash icon) all the files 
you want to get rid of. 

Customizing Turbo Pascal 



There are two sets of options that you can change to customize Turbo Pascal. The 
first set can be examined and changed using the Option command in the Turbo 
Pascal Edit menu. With it, you can set the tab width, toggle the auto-indent 
mode, and tell Turbo Pascal whether or not you want it to bring up a new ("Unti- 
tled") window each time you go into Turbo Pascal. Chapter 3 has more details on 
these options. 

The second set of options is under the Options command in the Turbo Pascal 
Compile menu. These options include toggling the auto-save mode, setting the 
size of the symbol table, and specifying default directories (path names) for units 
and include, resource, .REL, and output files. See Chapter 4 for more details. 
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where to Go from Here 



By now, you should be set up to start using Turbo Pascal. Boot up your system (if 
it isn't on), double-click on the Turbo icon, and go on to Chapter 2. It explains 
the different menu commands in Turbo Pascal. 

You may want to quickly jump to the glossary and scan through the Turbo 
Pascal icons shown there. That way, youll be more familiar with the different 
icons and the types of flies they represent before you begin programming. 
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CHAPTER 



Getting Started with Turbo Pascal 



Now that youVe all set up, let's plunge right into writing your first Turbo Pascal 
program. By the end of this chapter, you'll have written three small programs, 
saved them, and learned a few basic programming skills. The last section oflFers a 
game plan for proceeding through the rest of the manual^ depending on your 
programming experience. 

Loading Turbo Pascal 



If you re using a floppy-disk drive, first turn oflF your Macintosh. Put your Turbo 
Pascal disk into the internal disk drive. Turn the Mac on. The Mac boots up and 
displays a window with the contents of your Turbo Pascal disk. Near the top of 
the window, youll see an icon — ^labeled "Turbo" — of a hand waving a checkered 
flag. This is the Turbo Pascal compiler/editor. 

To launch it, just point at it with the mouse and click twice, rapidly. The 
desktop clears. A few moments later, a new menu bar appears, along with an 
empty window labeled "Untitled'' (see Figure 2-1). You're now set up to write 
your Turbo Pascal program. 



II 



Writing Your First Program 



A blinking vertical bar is in the left-hand corner of the ^Untitled** window. When 
you enter a program, the text you type appears here. Now type in the following 
program, pressing the l^i key at the end of each line: 

program MyFirst; 
begin 

WriteLn( 'HellO/ universe!'); 
ReadLn; 
end. 

Note the semicolons (;) at the end of the first, third, and fourth lines, as well as 
the period (.) after the last line. If you make a mistake while typing, press the 
f^-^ key to erase what you have typed. (If you're familiar with Mac-style editors, 
you can use the mouse to select and change text. ) 

Now go to the Compile menu and select the Run command (or press 
Turbo Pascal compiles and runs your program. If there is a syntax error (that is, a 
Pascal language error). Turbo Pascal stops at that place in your program and tells 
you what the error is. Acknowledge the error by clicking the mouse button or 
pressing the 1^1 key. Correct the error and then select the Run command again. 

After all errors are fixed. Turbo Pascal completely compiles your program and 
executes it. The menu bar and window disappear, a window labeled "MyFirst** 
opens, and the message Hello / universe! appears in the upper left-hand corner 
of the window. 




I 

Figure 2-1 The Compiled MYFIRST Program 

The program then waits for you to press l^--n (this is what the ReadLn state- 
ment does). When i'^i is pressed, the window disappears, and you're back in 
Turbo Pascal. 
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Saving Your First Program 



Having written and compiled this masterpiece, you need to save it to disk, so 
that you can modify it later. Go to the File menu and select the Save option (or 
press (^JXK- A file-save dialog box comes up. Type in a name for your program, 
say, *'MYFIRST. PAS.** Turbo Pascal isn't case-sensitive, so you can use uppercase 
or lowercase when entering information. Press and your program is saved to 
disk. 

If you exit Turbo Pascal (select Quit from the File menu), you'll see your 
program file saved as a document icon with a checkered flag on it. If you want to 
edit it some more, point the cursor to it and double-click. 

If you want to run your program outside of Turbo Pascal, go to the Compile 
menu and select the To Disk command (or press You don't need to save 

the file; just exit Turbo Pascal. You'll see your executable program, named 
MYFIRST, saved under a standard Mac application icon (a hand writing on a 
piece of paper). If you double-click on this icon, it will execute your Hello, 
universe! program again, then return you to the Mac desktop when you press 



Stepping Up: Your Second Program 



Now let's look at a second program that does a bit more. It prompts you for a 
location and a radius, then draws a black circle of that radius at the specified 
location. 

prograi MySecond; 

ases HemTypeS/ QuickDraw; 

var 

X,Y, Radius : Integer; 
TRect : Rect; 

begin 

tfrite( 'Enter X: '); 
ReadLn(X); 
Write{ 'Enter Y: '); 
ReadLn(Y) ; 

Write( 'Enter radius: '); 
ReadLn( Radius) ; 

SetRect( TRect ,X-Radius , Y-Radius , X+Radius , Y+Radius ) ; 

PaintOval(TRect); 

ReadLn; 

end. {of program HySecond > 
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The uses statement asks Turbo Pascal to let you use two units (program 
libraries), MemTypes and QuickDraw. This gives you access to the graphics data 
types and routines {Red, SetRect, and so on). 

You Ve declared four variables in this program: X, Y, Radius, smd TRect. X and 
Yare integers (numbers); they store the values you type in for the location of the 
center of the circle. Likewise, Radius is an integer that holds the radius (distance 
from the center to the edge) of the circle. TRect is a variable of type Rect, a 
special Macintosh data type that holds a description of a rectangle (top, left, 
bottom, and right values). 

The first six statements of the program consist of three Write statements and 
three ReadLn statements. Each Write statement writes the string inside of it out 
to the screen; each ReadLn statement waits for you to type a value and press 
Sl> after which it stores the value in the enclosed variable. 

The next two statements call QuickDraw routines. SetRect gives the variable 
TRect the boundaries indicated {X-Radius and so on). The resulting rectangle 
determines the size of the circle you want to draw. PaintOval takes the informa- 
tion in TRect and uses it to paint a black circle just within the rectangle's bound- 
aries. The last statement, ReadLn, causes the program to wait for you to press 
1"^! before it exits the program and returns to Turbo Pascal (or, if you Ve com- 
piled to disk, to the Mac desktop). 



Programming Pizazz: Your Third Program 



You ve now dabbled in graphics, so let's explore a more complex program. It 
ofiFers more variety and interesting graphics. 

prograi MyThird; 

uses MemTypes, QuickDraw; 

const 

Start = 50; 

Finish = ESQ; 

Step. = 5; 

var 

Xl,xa,Yl,Y5 : Integer; 

begin 

YX := Start; 
YB := Finish; 
XI := Start; 
while XI <= Finish do 
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begin 

X2 := (Start+Finish) - XI; 
MoveTo(Xl,Yl); 
LineTo(X2,YE); 
XI :» XI + Step 

end; 

XI :« Start; 
xa := Finish; 
Yl := Start; 
¥hile Yl <= Finish do 
begin 

Y5 := (Start+Finish) - Yl; 

MoveTo(Xl,Yl); 

LineTo(Xa,YE); 

Yl - Yl * Step 
end; 
ReadLn; 
end.{ of program MyThird > 

This program produces a square with a black center and some interesting 
patterns (known as Moire patterns) along the edges. The section labeled const 
defines three numeric constants (Start, Finish, and Step) that affect the size, 
location, and appearance of the square. By changing their values, you can change 
how the square looks. 

WARNING: Don't set Step to anything less than 1; if you do, the program will 
get stuck in what is known as an infinite loop. You won't be able to exit except by 
pressing the interrupt switch or by turning your Mac off. 

The variables XI, Yl, X2, and Y2 hold the values of locations along opposite 
sides of the square. The square itself is drawn by drawing a straight line from 
(XI, Yl) to (X2,Y2). The coordinates are then changed, and the next line drawn. 
The coordinates always start out in opposite corners: The very first line drawn 
goes fi-om (50,50) to (250,250). 

The program itself consists primarily of two loops. The first loop, as we men- 
tioned, starts by drawing a line from (50,50) to (250,250). It then moves the X 
(horizontal) coordinates by two, so that the next line goes fix)m (52,50) to 
(248,250). This continues until it finally draws a line fiom (250,50) to (50,250). 

The program then goes into its second loop, which pursues a similar course, 
changing the Y (vertical) coordinates by two each time. The routines MoveTo and 
LineTo are fix)m the QuickDraw unit. MoveTo moves to the indicated spot on the 
screen without drawing anything, while LineTo draws a line from the current 
location to the one given. 

The final ReadLn statement causes the program to wait for you to press i^i 
before exiting. 
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Where to Go from Here 



YouVe now gotten your feet wet and have written three quick programs using 
Turbo Pascal for the Macintosh. How do you proceed from here? 

If youVe a complete novice without any Mac or programming experience, read 
the rest of Part I very carefully, following all the examples shown. Make sure you 
understand each chapter before moving on to the next. If you re an experienced 
Mac user but you haven't done any programming, a quick once-through is all you 
need on Chapter 3. The rest of the chapters will require careful attention, 
though. 

If you're proficient on the Mac and have done a fair amount of programming, 
but not on the Mac, read Chapters 4 and 5 to familiarize yourself with Turbo 
Pascal. Then pay special attention to Chapters 6, 9, and 10. 

If you Ve done a lot of Mac programming but not in Pascal, then concentrate on 
Chapters 4, 5, 7, and 8. Chapters 6, 9, and 10 should then help you to see the 
diflFerences in programming with Turbo Pascal and whatever language you were 
using. 

If you Ve already used Pascal on the Mac, Chapters 4 and 7 will require special 
attention, while you can probably skim the rest. 

Finally, there are a few other books you might consider reading after youVe 
finished this manual. If you are planning to do much Mac-style programming 
with graphics, windows, menus, and so on, we recommend Inside Macintosh 
(Addison- Wesley, 1986). This consists of four softbound volumes (or hardbound 
and softbound set). It is the reference work for information on how to use the 
Mac Toolbox and operating system routines. If youVe not familiar with Pascal, 
youll probably want to pick up a good tutorial on the language. Many such books 
are available, including several that are specific to the Macintosh. 

We Ve tried to make this the best user's guide and reference manual possible. 
After working through it, you should feel at home with Turbo Pascal. Good luck, 
and happy programming! 
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CHAPTER 



Using the Editor 



In this chapter, you'll learn the basic editing features of Turbo Pascal — ^how to 
enter a program, move and format text, undo commands, and save files. 

A Quick Review of Clicking 



Remember, you should be familiar with the Macintosh — ^be able to click on 
icons, open and close folders and disks, and select commands from menus — 
before you go on. If you aren't, read the user's guide that came with your com- 
puter and familiarize yourself with those operations first. Let's quickly review 
the technique of clicking, however. 

Any movement of the mouse is echoed by the arrow-shaped pointer on the 
screen. When you place the pointer on, say, an icon and quickly press-and- 
release the mouse button, that's called clicking. It selects and highlights what- 
ever you just clicked on. You can then go to the menu and choose the command 
you want performed on the highlighted item. 

As a shortcut, you can double-click on the item to select and open it — ^and skip 
the menu-selection steps. 

Shift-clicking is another option. If you hold down and move the mouse to 
a second location, everything between the original mouse location and its cur- 
rent location is selected and highlighted. 



17 



Opemng Turbo Posad 



Getting into Turbo Pascal is easy. Look fer the liirbo Pascal icon, a hand waving a 
checkered flag, on your disk. Move the cursor to it and chck on it twice, rapidly. 
After a few seconds, the Macintosh desktop is replaced by the Turbo Pascal menu 
bar, and a window (labeled *Untided*) appears. 

You can also get into Turbo Pascal by clicking on its icon once, going to the File 
menu, and selecting the Open command (or press f^JOjV 

Close the ''Untitled' file by clicking on the Ckse box, then select Quit fiiom the 
File menu. You re back in the Mac desktop. Double-click on the MYFIRST.PAS 
file you created in the last chapter. A new window appears, called *MYFIRST.PAS,* 
with the program you entered previously. 

You can identify programs written wdth the Turbo Pascal editor; they look like 
a sheet of paper with the top right corner bent down and a checkered rectangle 
centered on the sheet. When you open one of these files, you start up Turbo 
Pascal, which opens a window with that program in it. 

Return to the Mac desktop. This time, double-click on the MYFIRST icon (a 
hand writing on a sheet). Your compiled program appears. Exit it by pressing 
E). The Mac desktop reappears. 

Editing a FUe 



An editor is a program that allows you to edit text, that is, to enter, delete, or 
change what you Ve typed in. Turbo Pascal has a built-in editor that is available at 
all times. With it, you can write new programs and modify existing ones. You can 
add, delete, and change code. The Edit menu shows some of these features. 
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Search Format Font Compile Transfer 
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Figure 3-1 The Edit Menu 
Let's start by typing in a new program. 



Entering a New Program 



Double-click the Turbo Pascal icon. An empty window (called ^'Untitled'*) covers 
most the screen. If someone has used this program previously and the window 
has text in it, close the window by clicking on the Close box in the upper left 
corner of the window. A blank screen with the desktop and Turbo Pascal menu 
bar remains; go to the File menu and select the New command (or press CUCSJ). 
Now you should have an empty window named '^Untitled." 

There are two difiFerent cursors on the screen. One is a vertical blinking bar in 
the upper left corner of the window. If you type the following line 

program Quickie; 

this cursor moves to the right as you type. It indicates where the next letter you 
type will appear. Press I^Hl . and the cursor moves to the start of the next line. 
Now type the following two lines, pressing R-*! after each one: 

var 
begin 

The bar cursor should now be at the start of the line underneath the word 
begin. 

The second cursor on the screen is larger and is shaped like an I-beam. It is 
'"connected" to the mouse; that is, it moves on screen as you move the mouse on 
your desk top. When you move this cursor outside the window, it turns into an 
arrow; move it back into the window, and it becomes an I-beam again. Now, 
move it right after the word var, then click once. The bar cursor jumps from the 
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beginning to the fourth hne to where the I-beam cursor was when you chcked 
the mouse button. Press E), indent two spaces, and type 

A,B,C : Integer; 

Your window should now have the following text: 

program Quickie; 
var 

A,B,C : Integer; 
begin 

The blinking bar cursor should be just after the semicolon (;) following the 
word Integer. Now move the I-beam cursor to the line below the word begin and 
click once. The bar cursor should jump down there. Add two space indents, type 
the following line, then press E): 

ffriteLn( 'Hello, world') ; 

If you correctly typed two spaces before starting WriteLn, the bar cursor 
should be indented two spaces in: It lines up with the word WriteLn. This is 
known as auto-indenting, and it helps you follow your programming conven- 
tions. (You can turn it oflF, if you like.) 

Now, press twice (it's located above RHl ). The bar cursor should be at the 
left margin again. Type end. (with a period) and press f^-H . Your entire program 
should now look like this: 
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program Quickie; 
var 






o 


FI,B,C : Integer; 
begin 
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Figure 3-2 


The Quickie Procedure Window 
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changing a Program 



There are several ways to change or modify a program. The simplest way is to 
add new text. Move the I-beam cursor to just after the semicolon following 
(Hello, world) and click once. The bar cursor moves there. Press and type: 

WriteLii( 'What's your sign?'); 

You Ve added a new line to your program. Because of the auto-indenting, this 
statement lines up with the one above it. 

The next simplest change is to delete text. Press 1^1 several times. You'll see 
that you're erasing what you Ve just typed. If you keep pressing it, or if you hold 
it down, it continues to erase the characters to its left. When you get to the start 
of the line, it jumps back up to the end of the previous line, and all the text below 
(which right now is just the line end .) moves up. If you re still holding 1^1 down, 
you'll find that your entire program will soon be erased, character by character. 
Stop, and retype all youVe erased. 

Suppose you wanted to change the string HellO/ world to Hi, world. Use the 
following steps: 

1. Move the I-beam cursor until it's between the O and the comma in 
Hello, world. Click the mouse once to move the bar cursor there. 

2. Press four times to delete ELLO. 

3. Type I (comma). 

Now, following the steps above, change the word WORLD to your own first 
name. 

The I Clear \ kev on the numeric keypad (or HOF^*-^ if you don't have a numeric 
keypad) is also used to delete text. When the cursor is in the middle of a line, 
pressing I Clear \ deletes all characters to the left of the cursor until the beginning of 
the line. This is handy in connection with the auto-indent feature when you want 
to un-indent a line, that is, remove blanks that were automatically inserted by 
pressing If you press I Clear \ when the cursor is at the beginning of a line, the 
line above is deleted. 

Selecting, Cutting, and Fasting Text 



A powerful feature of the Turbo Pascal editor is that it lets you cut portions of text 
and paste them elsewhere. You can use the I-beam cursor and the mouse to 
select portions of text — ^like setting aside selected pages of a document — ^while 
you decide what to do with them. 
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Let's say that you want to delete the variable declarations in your program. 
Move the I-beam cursor in front of the word var. Now, press the mouse button 
and hold it down. While holding the mouse button down, slowly move the 
I-beam cursor down the screen. Each line that it passes turns black with the text 
reversing (called inverse or reverse video). The text is what you are selecting. 
Now, with the mouse button still pressed, move the I-beam cursor until it's right 
in fix)nt of the word begin. The two lines above it, 

var 

A,B,C : Integer; 

should be in reverse video. Release the mouse button. The lines remain black 
because they are selected. 

You now have several options. To do nothing, move the I-beam cursor any- 
where and click once. The text will be de-selected; that is, it will return to 
normal. You can do this anytime you accidentally select text that you don't want 
selected. Try this out, then go back and re-select those two lines. 

The next option is to delete the selected text. You can press 1^1 . and the text 
will vanish. You can restore it by selecting Undo from the Edit menu, which is 
explained in a later section. The same thing happens if you go to the Edit menu 
and select the Clear command. You can also select the Cut command from the 
Edit menu (or press (^Si). That deletes the text but saves it in the Clipboard, a 
holding area for text that's been cut (or will be copied). Practice using these 
deletion options, then reenter the two lines. Select them again. 

The third option is to copy the selected text. Go to the Edit menu and select 
the Copy command (or press (HO- The selected text looks the same on the 
screen, but a copy of it has just been placed in the Clipboard. 

Fourth, you can replace the selected text. Whatever you start typing replaces 
the selected text. As soon as you press the first key, the entire selected text 
disappears and your new text replaces it as you type. 

If you have cut or copied text, so that you have text in the Clipboard, you can 
select the Paste command from the Edit menu (or press (^SJ)- The text in the 
Chpboard automatically replaces the selected text. 

If you have cut or copied text into the Clipboard, you can insert or paste it 
anywhere in your program. Select a line of text, then cut or copy it using the 
Edit menu. Now move the I-beam cursor to where you want to insert the text, 
and click the button once. The blinking bar cursor appears there. Go to the Edit 
menu and select the Paste command (or press Q[3). The selected text is now 
pasted where the cursor is. A copy of that text is still in the Clipboard; you can 
move somewhere else and paste it in again. 
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Try out these commands, until you're comfortable with them. Then you can do 
the following exercises: 

1. Change the name of the program to Mortiraer by selecting the word 
Quickie and then typing Mortiier. Practice selecting individual words 
and letters on a given line. 

2. Delete the var and A,B,C : Integer; lines using three difiFerent means. 
Retype or paste them back in each time. 

3. Insert the statement Write Ln ( ' A is A . ' ) ; between the first and second 
WriteLn statements. (Don't forget the semicolon at the end.) 

The Undo Command 



During the exercise above, you may have accidentally deleted or changed some- 
thing. You probably went in and retyped the altered text. The Turbo Pascal 
editor helps protect you from your own mistakes with the Undo command in the 
Edit menu. 

Try the following exercise. Move the I-beam cursor to the start of the program, 
hold the mouse button down, and move the I-beam cursor to the end of the 
program. The entire program should now be selected. Now press 1^^ - Presto! 
Your entire program has just disappeared! Don't panic. Instead, select the Undo 
command in the Edit menu (or press Your entire program resurfaces. 

You can only Undo the last action you did. Select var, for example, and press 
var disappears. Now move the cursor to the end of the program. If you click 
on the Edit menu, Undo appears blurred; that is, it cannot be selected. Even if 
you move the cursor back to the empty line and select Edit, Undo will still be 
blurred. You have to retype var; the selection can't be undone. 

Spend some time experimenting with the Undo command, seeing what you 
can (and can't) undo. This is a really valuable command, so take the time to learn 
it well. 



Formatting Text 



Many Pascal programmers format their programs with indentation, ahgning 
begin and end keywords, nested statements, and so on. Often a level of nesting 
will change: A set of statements will be moved out of an if.. then statement, or 
into a for loop. To maintain the correct nesting format, the programmer then has 
to shift all the code — ^line by line — ^left or right, according to the change. 
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With the Turbo Pascal editor, such formatting changes are easy. Just select the 
text to be shifted, using the click-and-drag technique: Put the pointer at the 
beginning of the selected text, hold the button down, and move to the end of the 
text. Release the button. Then press to shift left, or {^jfj^ to shift right. 

Each press of the command sequence shifts the entire selected block of text one 
character left or right. You can also do this by selecting the Shift Left or Shift 
Right commands in the Edit menu. 

Finding a Lost Bar Cursor 



The location of the bar cursor — ^the short, blinking one that indicates where the 
next character you type will appear — ^is quite diflFerent from the location of the I- 
beam cursor, the one reflecting mouse movements. In a large file, it is possible to 
lose the bar cursor, because of scrolling to (that is, viewing) a diflFerent part of the 
program from where the bar cursor is. Two commands in the Turbo Pascal editor 
help you to deal with that. 

First, if you press (^-^ (or SJEJ), the text display will be scrolled upwards or 
downwards until the first or last line in the window is the line with the bar 
cursor. No text vnll be changed. Second, you can use the Home Cursor com- 
mand in the Search menu (or press QE)). This moves the bar cursor to the very 
top of the file and adjusts the display to show it. 

Search and Replace 



The Turbo Pascal editor lets you search for a particular string (that is, a deUmited 
group of characters). It also lets you change one string for another. 

To find a given string, such as a variable or procedure name, select the Find 
command in the Search menu (or press (^Ii|). A dialog box comes up that asks 
you to specify what you want found. There are two checkboxes, Words Only and 
Case Sensitive. The first means that it won't recognize the string if it's embed- 
ded in a larger string. For example, if you are looking for myGlobals and selected 
this option, then it wouldn't pick out the string in myGhbalsH , Second, specify- 
ing Case Sensitive means that uppercase and lowercase letters are not consid- 
ered to be equivalent. If you are looking for myGlobals, then MyGlobals doesn't 
match. 

Having typed in your string, start the search by pressing l^"*! or by selecting 
the OK button in the dialog box. The editor starts searching from the current 
position of the bar cursor until it either finds the string requested or hits the end 
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of the file. If it finds the string, that section of your program appears on the 
screen, with the specified string highlighted. If it doesn't find the string, it beeps 
at you, and the screen stays the same. 

Having found the first instance, you can find the next appearance of the string 
by selecting the Find Next command from the Search menu, or by pressing 
I jjTD You can also select Change to replace one string with another. 

You can use key equivalents in the Search and Replace dialog box; that is, you 
can type (TJ for Yes, CO for No, (T) for All, and for Cancel. 



Saving Your Text 



There are several ways of saving the text you have entered in a window: 

• Select the Save command in the File menu (or press (^XO)- If your window 
already has a title, the text is saved on the disk, overwriting the old version of 
the file. If your window is untitled, the Save-file dialog box comes up. Select 
the proper drive and directory, type in a name for your text, and click the Save 
button (or press After saving the text, your window's title is changed to 
the file name you just entered. When naming your files, it's advisable to use 
extensions, for instance .PAS for Pascal programs and .R for RMAKER source 
files. This enables you to use the same name for diflFerent files relating to the 
same application, such as MYPROG.PAS and MYPROG.R. Furthermore, 
it makes it easy to determine the type of a textfile without having to actually 
read it. 

• Select the Save As command in the File menu. This corresponds to the Save 
command, except that it always brings up the Save-file dialog box, thus allow- 
ing you to save the text under a new name. 

• Select the Close command in the File menu (or press This saves the text 
(corresponding to the Save command) and removes its window fi*om the desk- 
top. The Close command only saves the text if it has been modified since it was 
last saved, or since the window was opened. 

• Click on the window's Close box. This corresponds to selecting the Close com- 
mand in the File menu. 

• Select the Quit command in the File menu. This closes all windows and 
returns to the Macintosh desktop (the FINDER). 

Now that you know how to edit your program, let's move on to Chapter 4. 
You'U learn how to tell the computer to carry out your program. 
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T E R 4 

Using the Compiler 



You now know how to create a program and save it to disk. Now, let's look at how 
to tell the computer to carry out the instructions youVe typed in. This is done 
with the commands in the Compile menu. 
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Figure 4-1 The Compile Menu 



Well briefly describe the Run command, then examine all the other com- 
mands in the Compile menu: Run, To Memory, To Disk, Check Syntax, Find 
Error, Get Info, and Options. Well also explain how Turbo Pascal handles syntax 
and run-time (system) errors. 
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An Overview of the Run Command 



Say youVe typed in a program using the Turbo Pascal editor. To make it run, pull 
down the Compile menu (click on Compile in the menu bar) and select the first 
option. Run. You can avoid using the mouse by pressing [i|2J. Turbo Pascal 
then compiles your program, that is, changes it from Pascal (which you can read) 
to 68000 machine code for the microprocessor (which the Macintosh can exe- 
cute). You don't see the 68000 machine code; it's stored oflF in memory some- 
where. 

While the program is compiling, the cursor is changed to a racing flag and a 
small box (or window) appears at the top of the screen, saying Compiling: <file 
nanie>. The box includes a button labeled Cancel. Use it to stop the compiler for 
any reason — ^for example, if youVe suddenly remembered a change you forgot to 
make to your program. Just move the cursor over the word Cancel and click the 
mouse button. Turbo Pascal then returns you to the editor. 

Should an error occur during compilation. Turbo Pascal stops compiling and 
returns to the editor, with the cursor at the error location. A dialog box tells you 
what the error was. Click on the error box, correct the problem, and select Run 
again. 

Once the translation from Pascal to machine code is complete, Turbo Pascal 
tells the Mac to execute the code it has generated and your program runs. Your 
program takes control of the Mac and completely replaces the Turbo Pascal 
screen and menu bar. 

If a run-time error crops up — ^that is, an error occurs while your program is 
executing — you 11 get the standard Mac system error box. This is a box with a 
bomb icon in it and two buttons: Restart and Resume. If you select the Resume 
button, you return to the Turbo Pascal editor. When possible, the cursor is at the 
section of code where the error took place; for some errors (such as pressing the 
Interrupt switch on the side of the Mac), there is no way of determining what 
part of the program was executing when the error occurred, so the cursor is 
placed at the beginning of the text. Restart reboots your computer. 

NOTE: You should not use the Interrupt switch on the Mac Plus unless the 
debugging program MACSBUG is loaded. Without MACSBUG, the program 
merely goes into a simple debugger built into the Mac; a bomb box showing you 
the error doesnt appear. 

When you press Resume, a box pops up, telling you what the error was (input/ 
output, division by zero, and so on). After you figure out how to fix the program 
bug, you can recompile and run the program again. 

When your program has finished executing, the Macintosh returns control to 
Turbo Pascal, and you re back where you started. You can now make changes to 
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improve or cause your program to do something difiFerent. If you select the Run 
command at this point without changing your program, Turbo Pascal immedi- 
ately executes it, without recompiling. 

The Turbo Pascal Compiler 



You can now run your programs. As you have seen, Turbo Pascal is very forgiving 
of errors and does its best to help you track down and fix them. Because of Turbo 
Pascal's accommodating structure and high speed of compilation, the cycle of 
entering, testing, and correcting your program wastes little time. Let's look at 
different aspects of that cycle in more detail. 

So, Whafs a Compiler Anyway? 



The Macintosh, Uke most microcomputers, has a central processing unit (CPU) 
that does most of the work. On the Mac, the CPU is a single chip: the 68000, a 
microprocessor designed by Motorola. The 68000 has a set of binary-coded 
instructions that it can execute. By giving the 68000 the right sets of instruc- 
tions, you can make it draw objects on the screen, perform math, move text and 
data around — ^in short, do all the things that you want it to do. These instructions 
are known collectively as machine code. 

Since machine code consists of pure binary information, it's neither easy to 
write nor easy to read. You can use a program known as an assembler to write 
machine-level instructions in a form that you can read. This is known as pro- 
gramming in assembly language. However, you still have to understand just how 
the 68000 microprocessor works. You'll also find that to perform simple opera- 
tions — such as printing out a number — often requires a large number of instruc- 
tions. 

If you don't want to deal with machine code or assembly language, you use a 
high-level language such as Pascal. You can easily read and write programs in 
Pascal, because it is designed for humans, not for computers. However, the Mac 
understands only machine code. The Turbo Pascal compiler translates (or com- 
piles) your Pascal program into instructions that the computer can understand. 
The compiler is just another program that moves data around; in this case, it 
reads in the text of your program and writes out the corresponding machine 
code. 
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what Gets Compiled? 



You can edit up to eight diflFerent Turbo Pascal programs at the same time, each 
with its own window. If you have several windows open, which one is aflFected 
when you select a command from the Compile menu? As with the editing com- 
mands, it's the program in the currently active window, that is, the window 
whose title bar has horizontal lines and a close box in it. All the other (inactive) 
windows have nothing in the title bar except for the window's title (either the file 
name or ^'Untitled*). 

As with the editor, to make a window active, you move the cursor into it and 
click the mouse once. If the windows overlap, this brings the one you just 
selected to the front, so that you can see the entire window. 

You can also use the Window command in the Search menu. Selecting the 
Window command brings the first window you opened to the fi-ont, and so on 
sequentially. 

Where's the Code? 



When you use the Run command. Turbo Pascal saves the resulting machine code 
in memory (RAM). This has several advantages. First, the compiler runs much 
faster, since it takes less time to write the machine code out to RAM than out to a 
floppy or hard disk. Second, since your program is already loaded into RAM, 
Turbo Pascal just tells the Macintosh to execute your code. Thirds the Mac more 
easily returns to Turbo Pascal once your program stops executing, since Turbo 
Pascal also stays in RAM the whole time. Fourth, Turbo Pascal allows you to 
open several program windows and compile them to RAM. You can then execute 
each of them without recompiling. 

If compiling to RAM is so wonderful, why wouldn't you want to do it every 
time? Two reasons. First, you would be able to run your programs only from 
Turbo Pascal. If you compile only to RAM, the resulting machine code is never 
saved on the disk, so you have no way of executing your program from the 
Finder. You also have no way of copying your program. 

Though less likely, the second problem is memory: You might not have 
enough. It could happen if you're using a "thin" (128K) Mac, if your program is 
very large, if your program uses a lot of memory for dynamic data allocation, or if 
you have opened several windows and have compiled each of them. 

It's easy to produce a code file (application) that you can run from outside 
Turbo Pascal: Select the To Disk option in the Compile menu (or press QCO)- 
This produces a code file that you can run from the Mac desktop by double- 
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clicking its icon, or from within Turbo Pascal by using the Transfer command in 
the File menu. 

The file produced by a (Compile) To Disk command has the name used in your 
program header. In other words, if your program has the header 

prograi MyOwnProgram; 

then the resulting code file is named MYOWNPROGRAM. However, you can 
specify a different file name (and a particular volume or subdirectory) by using 
the $0 compiler option, such as 

{$0 Turbo: code: My Prog} 

Appendix C, **Compiler Directives," has more details. In either case, the icon 
used is the standard Mac application icon of a hand writing on a piece of paper. 
You can create your own icon using a resource file; see Chapter 9 for further 
details. 

Unlike the Run command, the To Disk command does not automatically exe- 
cute your program once the compilation is done. You can execute it using the 
Transfer command in the File menu or by leaving Turbo Pascal and clicking on 
the icon. Or you can recompile it to RAM with the Run command, which then 
automatically executes it. 

You may want to compile a program to RAM without running it. Perhaps you 
have several programs open, and you want to compile each of them to RAM 
before running them. In this case, select the To Memory command in the Com- 
pile menu (or press QSI). It works just like the Run command with two ex- 
ceptions. First, it does not execute the program once compilation is done; 
instead, it leaves you in Turbo Pascal. Second, it always compiles the program, 
while the Run command recompiles only if you Ve modified the program since 
the last compilation. If you use the To Memory command, and select Run with- 
out making any changes to the program, the Run command won't recompile your 
program. 



Syntax Errors 



Just like Enghsh, Pascal has rules of grammar that you must follow. However, 
Pascal's rules are fairly strict, much more so than those of Enghsh. You can use 
poor grammar in speaking and still be understood; if you use poor ^grammar'' in 
your Pascal program, however, the compiler won't understand what you want. 
The result is a syntax error, which happens when you don't use the appropriate 
words or symbols in a statement, or when you organize them incorrectly. 

When the compiler detects a syntax error, Turbo Pascal stops the translation 
and goes back to the editor. Once there, it moves the cursor to the spot in your 
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program where the error occurred. It then displays a box across the top of the 
screen, explaining (in brief terms) what the error was. Press i^i to make the box 
go away, or move the cursor (via the mouse) into the box and cUck the mouse 
button. 

What syntax errors are you likely to get? Probably the most common error 
novice Pascal programmers make is Unknown identifier. Pascal requires that you 
declare all variables, data types, constants, and subroutines — ^in short, all identi- 
fiers — ^before using them. If you refer to an identifier that you haven t declared, 
or if you misspell it, you'll get this error. Other common errors are ' ; ' expected, 
which means that you need to put a semicolon at the end of the previous state- 
ment, and ' :-' expected, which means that you need to use the assignment 
operator (:=) instead of the equals sign (=). Appendix B, **Error Messages and 
Codes," lists all the compiler syntax errors. 

You can check for syntax errors without compiling the program by using the 
Check Syntax command in the Compile menu (or pressing fgJxl) - Turbo Pascal 
then checks your program's syntax, but doesn't produce any machine code. This 
is faster than compiling to disk, so it's a handy way to clean up syntax errors 
before producing a code file. On the other hand, it isn't significantly faster than 
compiling to memory, so consider using the Run or To Memory commands 
(unless you want to avoid compiling to memory for the reasons previously dis- 
cussed). 

Run-time ( System) Errors 



In programming, sometimes just following the rules governing correct syntax 
isn't enough. For example, suppose you write a simple program that prompts 
you for two integer values, adds them together, then prints out the result. The 
entire program might look something like this: 

progran AddNums; 
var 

A,B,C : Integer; 
begin 

Write( 'Enter two integer values: 
ReadLn(ArB) ; 
C := A + B; 

WriteLnCThe sum is ',C); 
end. 

In response to the prompt Enter two integer values:, say you type in real 
numbers (that is, numbers with decimal points), integer values that are too 
large, or even character strings instead of numbers. What happens? The Mac 
system error window appears, with the bomb icon and an error ID code in it. 
You are given two options, each presented as a button: Restart and Resume. 
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The Restart button, which you can always use, reboots your Macintosh, just as 
if you had turned your Mac off and on or you had pressed the Reset switch on the 
side of your Mac (assuming you have one installed; it's the one closest to the 
front). This button is best used only when you have no other option. 

If you are running from within Turbo Pascal, you can select the Resume button 
instead. It puts you back into Turbo Pascal, with your windows (and files) still 
intact. This means that even if you didn't have the Auto Save option selected, the 
program file you ve been editing for the last hour isn't gone. It's still there — 
unless, of course, your program went totally amok and wrote over large portions 
of memory (in which case you wouldn't have been able to get back to Turbo 
Pascal anyway). 

For errors within a Turbo Pascal program, such as division by zero, range 
overflow, and I/O error, the cursor is moved to where the error took place, and a 
window with the bonib icon and a description of the error type appears. You 
must acknowledge the error by moving the cursor to the message window and 
clicking the mouse, or by pressing l-^l . The window goes away, and you can 
figure out what changes (if any) to make to your program. If, after moving around 
in your program, you want to find the error again, select the Find Error com- 
mand from the Compile menu (or press [^(3). Turbo Pascal quickly recompiles 
your program (without producing code) and places the cursor where the error 
took place, with the bomb box again explaining the error. 

Should the error occur within an include file (the next chapter has more infor- 
mation on include files). Turbo Pascal automatically opens a window for that file, 
reads it in, and moves the cursor to the error's location. If a window for that file is 
already open, that Mdndow is brought to the front, and the error located. 

There's a way to go out on a limb and deliberately trigger a Mac system error: 
Press the Interrupt switch on the side of the Mac (assuming you have one 
installed; it's the one closest to the back). You might need to do this if, for exam- 
ple, your program is stuck in some section of code, such as an infinite loop. You 
won't be able to use the Find Error routine to locate where your program was 
when you interrupted it, but you can get back to Turbo Pascal without losing 
your program text and the cursor may be positioned at the point in the program 
where the execution was. 
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The Get Info Command 



The Get Info cx>mmand, which you can also invoke by pressing SJXI> brings up 
a window that tells you how big the text of your Pascal program is, both in 
bytes and in lines. If you haven't compiled your program yet, or if you Ve made 
changes since your last compilation, it'll tell you that the program is Not 
compiled. Otherwise, it gives you the size of the code (in bytes) as well as the 
number of bytes that will be allocated for data when the program is run. Finally, 
it tells you how large the heap is and how much of that space is available. (The 
heap is where dynamic variables are created using the standard procedures New 
and Dispose.) Click on the OK button to make it go away, or press S-H . 

The Options Command 



The last item in the Compile menu is the Options command, which doesn't have 
a keyboard equivalent. It allows you to set up some default information for use 
by the Turbo Pascal compiler. First, you can decide how much space (in kilo- 
bytes) to allocate for the symbol table. The default is 32K, which is the maximum 
size. If you're running on a 128K Mac, you might want to make it smaller to get 
some memory back for compilation. 

Second, you can set Auto Save to take eflFect when Run is selected. Auto Save 
automatically saves all edited windows to the disk when the Run command is 
selected from the Compile menu. Turbo Pascal keeps track of whether you've 
made changes in a given window since the last time you saved it to disk. When 
you select Run, Turbo Pascal first performs the Save command for all windows 
that have been modified. 

Finally, you can set the default directories for all the compiler directives that 
reference files: $U (units), $1 (include files), $R (resource file), $L (assembly 
language .REL files), and $0 (output file). These compiler directives are dis- 
cussed in further detail in Appendix C. Having made the changes you want, 
select either the OK button, which allows you to use these options, or the Cancel 
button, which ignores whatever changes you've made to the options. In either 
case, you're returned to the Turbo Pascal editing window. 

If you want to make these options your standard settings, select the Save 

Defaults command in the File menu. 

The ability to specify directories is very useful if you're running under Apple's 
Hierarchical File System (HFS) and want to keep these files in diflFerent sub- 
directories. If you don't specify a directory for a given option, the current direc- 
tory is assumed. However, if the compiler option itself contains the directory 
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(such as {$1 Turbo:otherstuff:linked.lib}), then the default directory (blank or not) 
is ignored completely. 

Now that you're acquainted with the commands in the Compile menu com- 
pletely, you're ready to move on to the next chapter. In it, you'll learn how to 
create a "textbook" Pascal program. 
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CHAPTER 



Writing Textbook Pascal Programs 



This chapter gives you the information you need to take standard Pascal pro- 
grams out of textbooks and get them to run under Turbo Pascal. We'll review 
briefly how to create and save a program, then go into the Pascal run-time envi- 
ronment. Well also cover compiler directives, input/output error checking, and 
range checking. 

Turbo Pascal makes it easy for you to create a standard or ''textbook'' Pascal 
program on the Macintosh. No special knowledge is required; you just type in 
your program, compile it, and run. Turbo Pascal sets up a window for you and 
treats it like a plain CRT monitor. You can write to the screen, prompt for (and 
receive) input, move the cursor around, have the screen automatically scroll, and 
so on. 

In other words, you don't have to know anything at all about the innards of a 
Macintosh to start writing Pascal programs on it. Most routines you find in text- 
books run just fine under Turbo Pascal, with a few exceptions that well discuss 
later in this chapter. 

To start with, let's review how to get a new program typed in and running. 
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Creating a Program: A Quick Review 



To write and run a program, you need only follow the steps you ve learned so far. 
Here's the procedure: 

1. Move the mouse to the Turbo icon and double-click on it. Turbo Pascal 
brings up its menu bar and presents you with a blank program window 
labeled ^Untitled". If this window doesn't appear (which could happen 
if you Ve disabled the Startup Window option using the Options com- 
mand in the Edit menu), create a new window with the New command 
in the File menu (or press (^UJ). 

2. Type your program in, using the keyboard, mouse, and menu com- 
mands discussed back in Chapter 3. Save it out to disk using the Save 
command in the File menu. Select the Options command in the Com- 
pile menu, and enable the Auto Save option if it's not ateady enabled. 

3. Select the Run command from the Compile menu (or press (^[SJ). If 
an error is found, Turbo Pascal returns you to the editor. Correct the 
error and select the Run command again. 

4. Once you've corrected all syntax errors, your program will execute. If 
you have run-time errors, the Mac System Error box will appear. If that 
happens, click on the Resume button. You'll find yourself back in the 
Turbo Pascal editor, with the cursor placed where the error occurred, if 
it can be located. Correct the error, and select Run again. If you totally 
crash the system somehow, reboot the Mac and double-click on your 
program document icon. You'll be returned to Turbo Pascal, and you 
can edit your program. (This is why you set the Auto Save command: 
So that your source code is automatically saved to disk before each Run 
command.) 

5. Once you've corrected all your run-time errors, save your program to 
disk again (select the Save command from the File menu, or press 
[^JJJ). Now select the To Disk command from the Compile menu (or 
press (^|2D. When that's done, exit Turbo Pascal by selecting Quit 
fiiom the File menu (or press QC^. 

6. Your program is now an executable file, appearing as the standard Mac 
application icon (a hand writing on a blank piece of paper). You can run 
it any time by double-clicking on that icon. 

Let's look at some sample programs based on Standard Pascal. 
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Sample Pascal Programs 



Consider the following program: 

prograi Product; 
var 

A/B : Integer; 
C : Real; 

begin 

Write( 'Enter two integer values: '); 
ReadLn(A,B) ; 
C := A * B; 

WriteLn('The product is ',C:fl:2); 
ReadLn; 
end. 

This program runs as written. A window (labeled ''Ratio'') is created. The 
prompt Enter two numbers ; is written in the upper left corner of the window, and 
the blinking cursor sits a few spaces past the end of the prompt. The program 
then waits for you to type in two integer values. You may separate them with a 
blank or a carriage return, and you can use l-^i to delete and retype what you Ve 
entered. 

After you type the second value, press SJ. The program calculates A*B (con- 
verting to real) and assigns the resulting value to C. It then writes out the mes- 
sage The product is, followed by C's value in a field eight characters wide, with 
two digits appearing after the decimal point. 

The program then waits for you to press EJ, at which point it closes the 
window and returns either to Turbo Pascal (if executed with the Run command) 
or the Finder (if executed from the desktop or by using the Transfer option in the 
File menu). 

Here's a second, even quicker example: 

prograa Table; 
var 

I : Integer; 

begin 

for I := 1 to IDD do 

WriteLn(I:3,' ',{I*I):t); 
ReadLn; 
end. 

When you run this program, you'll notice a few things. First, the window is 
now labeled ''Table" to match the name in the program header. Second, Turbo 
Pascal scrolls the screen, just like a regular monitor, when you get to the bottom 
of the display. You may, at any time, stop screen output by pressing the mouse 
button and holding it down. When you release it, output continues. This is 
handy to keep text from scrolling oflF the screen before you have read it. 
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The Pascal Run-time Environment 



The key to writing Standard Pascal programs is to simply type in the programs as 
you see them in your textbook. By default, Turbo Pascal links in a set of routines 
that implements Standard Pascal I/O on the Mac. These routines perform all the 
initialization that your program needs to be able to run on the Macintosh. They 
also create a simple Macintosh window that acts like the standard text screen of a 
terminal or personal computer. It displays 25 lines of text, with up to 80 charac- 
ters on each line. The screen-like window disappears when your program ends 
execution. 

Within this environment, the procedures Read, ReadLn, Write, and WriteLn 
function as expected, handling carriage returns and form feeds. Turbo Pascal also 
scrolls the display when necessary, as the second example program demon- 
strates. What's more, you can directly position the cursor using GoToXY and 
perform other screen operations using special Turbo Pascal procedures and func- 
tions. These are described in Chapter 25. 

The Standard Pascal environment is actually implemented as a group of four 
units: PasSystem, PaslnOut, PasConsole, and PasPrinter. A unit is a library or 
collection of useful subroutines and other declarations. 

The unit PasSystem is always used, since it provides certain functions needed 
by all Turbo Pascal programs. The next two — PaslnOut, and PasConsole — ^are 
also automatically used unless you set the {$U-} option. The last one, PasPrinter, 
is used only if you explicitly request it. For more details on using (or not using) 
units, see Chapter 7. 

Compiler Directives 



Most Pascal compilers allow some form of compiler directives. These are com- 
mands to the compiler, embedded in comment statements within your program. 
They typically take one of two formats: 

{$<letter><+ or ->} 
or 

{$<letter> <filenanie>} 

The first form is used to turn some option on or off For example, {$RH-} teUs 
the compiler to produce range-checking code, while {$R-} tells it not to. 
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The second form usually directs the compiler to read from or write to some 
file. For example, the directive {$1 MYLIB. PAS} tells the compiler to include the 
file MYLIB. PAS at this point in the program — in other words, to go to that file 
and read from it as if the text in that file had been inserted in the current pro- 
gram file. 

All the compiler directives are documented in Appendix C, but here are some 
of the most commonly used directives. 

Input/Output Error Checking 



An issue often addressed in Pascal textbooks and classes is how to make your 
code **crashproof that is, how to set it up so that users can't cause your pro- 
gram to stop due to input/output (I/O) errors. For example, say you ran the first 
example program, PRODUCT, and, at the prompt Enter two integer values:, 
typed in a real value (that is, a number with a decimal point). Your program 
would halt, with a Mac system error box popping up. In a short program like 
this, such an error isn't a big bother. What if you were entering a long list of 
numbers, however, and had gotten most of the way through before making this 
mistake? You'd be forced to start all over again. So, making your program crash- 
proof is important. 

Like most compilers, Turbo Pascal allows you to disable automatic I/O error 
checking and test for it yourself within the program. To turn off I/O error check- 
ing at some point in your program, include the compiler directive {$1-}. This 
instructs the compiler not to produce code that checks for I/O errors and brings 
up the Mac system error box when one does occur. For example, we could mod- 
ify the program PRODUCT to look like this: 

prograi Product; 
var 

A,B : Integer; 
C : Real; 
begin 

Write ('Enter two integer values: '); 

{$!-> { turn off I/O error checking } 

ReadLn(a,B); 

{$!+} { turn it back on } 

C := A * B; 

WriteLn('The product is ',C:fl:a); 
ReadLn ; 
end. 

Now, no matter what you enter for A and B, you won't get a Mac system error 
box. That doesn't mean that there are no errors nor that A and B will have the 
values you think they do. If you make a mistake, the corresponding variable just 
gets the value zero (0). 
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With I/O error checking disabled, you can check for an error by calhng the 
standard Turbo Pascal function lOResult, lOResult returns an integer value cor- 
responding to the appropriate Mac I/O result code (see Appendix C). If the 
result is 0, then no error has occurred; otherwise, you'll probably want to take 
some action, even if it's just to ask for the values again. Your code might look like 
this: 

prograi Product; 
var 

A/B : Integer; 
C : Beal; 
begin 
{$!-} 
repeat 

Hrite( 'Enter two integer values: '); 
ReadLn(A,B) 
until lOResult = D; 

C := A » B; 

WriteLn('The product is 'fC:fl:5); 
ReadLn; 
end. 

You need to be aware that each call to lOResult clears it; that is, sets it to zero. 
Also, each I/O call (Write, WriteLn, Read, ReadLn, Assign, Reset, Rewrite, and 
so on) sets lOResult to an appropriate value. For example, the following code 
wouldn't work properly: 

prograi Product; 
var 

A,B : Integer; 
C : Real; 
begin 
{$1-} 
repeat 

Write{ 'Enter two integer values: '); 

ReadLn(A,B); 

if lOResult <> D then 
WriteLn( 'Error on inputl') 
until lOResult = D; 
{$1+} 

C := A » B; 

WriteLn('The product is ',C:fl:E); 
ReadLn; 
end. 

There are two reasons this wouldn't work. First, the call to lOResult in the if 
statement if lOResult <> D clears it, so that the call in the until clause doesn't 
represent what happened with the ReadLn(A,B). Second, the call to WriteLn 
changes lOResult anyway. If you did want to print this message out, you'd have 
to do something like the following program. 
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prograi Product; 
var 

a,B/IOCode : Integer; 
C : Real; 

begin 
{$!-} 
repeat 

Write( 'Enter two integer values: '); 

ReadLn(A,B) ; 

lOCode lOResult; 

if lOCode <> Q then 
WriteLn( 'Error on input!') 
until lOCode D; 
{$I+> 

C :» A * B; 

WriteLnCThe product is '/C:fl:2); 
ReadLn; 
end. 

By saving lOResult in lOCode, we avoid both problems, since we only refer- 
ence lOResult once (right after the place where we want to check for errors). For 
more sophisticated applications, you can take some action (for example, print a 
message) on the actual value of lOCode. 



Range Checking: The {$R+I-} Directive 



Another common compiler directive is {$R+/-}. It controls range checking of 
array and string indexes, and assignment to scalar data types. By default, range 
checking is turned oflF ({$R-}); you can turn it on with {$R+}. 

This directive is used to track down errors caused by using array indexes that 
are out of bounds or by assigning out-of-range values to scalar variables. Suppose 
you had the following program: 

prograi RangeTest; 
var 

Indx : Integer; 
List : array [1.. ID] of Integer; 
begin 

for Indx := 1 to ID do 

ListCIndx] := Indx; 
Indx := D; 

while (Indx < 11) do 
begin 

Indx := Indx + 1; 

if ListCIndx] > D then 
ListCIndx] := -ListCIndx] 

end; 

for Indx := 1 to ID do WriteLn(ListCIndx] ) ; 
ReadLn; 
end. 
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If you type in this program, it will compile and run. And run. And run. It will, 
in fact, get stuck in an infinite loop. Look carefully at this code: The while loop 
executes 11 times, not just 10, and the variable Indx has the value 11 the last time 
through the loop. Since the array List only has 10 elements in it, Listfll ] points 
to some memory location outside of List, Because of the way variables are allo- 
cated, List[ll] occupies the same space in memory as the variable Indx. This 
means that the statement 

ListCIndx] := -ListCIndxl 

is equivalent to 

Indx := -Indx 

Since Indx equals 11, this sets Indx to -11, which starts the program through 
the loop again. That loop now changes additional bytes elsewhere, at the loca- 
tions corresponding to List[-11..0]. 

In other words, this program can really mess itself up. And since Indx never 
ends the loop at a value greater than or equal to 11, the loop never ends. 

How do you check for things like this? Insert {$R+} at the start of the pro- 
gram. When you run a faulty program, you'll get a Mac system error box. Press 
the Resume button, and you're back in Turbo Pascal, at the right bracket (]) in 
the statement if List [Indx] > D. A box appears with the error message Range 
check failed. This tells you that Indx has some value outside of List's array 
bounds (1..10). 

You can leave range checking on all the time just by placing {$R+} at the start 
of each program you write. However, the code generated to do range checking 
does make the program larger and slower. Also, there are some situations — 
usually in advanced programming — ^in which you might want or need to violate 
range bounds, most notably in working with dynamically allocated arrays, or in 
using Succ andPred with enumerated data types. 

You can selectively implement range checking by placing the {$R+ } directive 
at the start of the code that needs it, then placing the {$R-} directive at the end of 
the code. For example, you could write the loop above as: 

while Indx < 11 do 
begin 

Indx := Indx + 1; 
{$R+} 

if ListEIndxl > 0 then 
ListCIndxl := -Listtlndx] 
{$R-> 
end; 

Range checking will only be performed in the if.. then statement and nowhere 
else in the program. Unless, of course, you have other {$R+} directives else- 
where. 
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Include Files: The {$I<file)} Directive 



Another commonly used compiler directive, {$I(file)}, allows you to break one 
large program file up into several smaller files. (Don't confiise this with the 
{$!+/-} directive used for I/O error checking.) {$Kfile)} directs Turbo Pascal to 
include (file) during compilation. Turbo Pascal then opens this file and reads the 
Pascal code from it, compiling it as if it were part of your program. When it 
reaches the end of the included file, it closes the file and continues to compile 
your program. 

Most Macintosh-style applications can be organized into chunks, each chunk 
containing related procedures and fimctions. If you were writing a bulky pro- 
gram, you could organize it as follows: 

prograi BigJob; 

{$1 BigJob. Def} < global declarations and definitions } 

{$1 BigJob. Util) { utility procedures/functions } 

{$1 BigJob. Menu) { menu-driven procedures/ functions } 

{$1 BigJob. Event} < event-handling procedures/functions } 

{$1 BigJob. Init} { initialization and cleanup procedures } 
begin 

Initialize; 

repeat 
SystemTask; 

if GetNextEvent(theEvent) then 
HandleEvent(theEvent) 
until Finished; 
Cleanup 

end. { of program BigJob > 

This program text is placed in a file called BIGJOB. PAS. In addition, five 
other text files (BIGJOB. DEF, and so on) contain the appropriate parts of the 
program. Since Turbo Pascal allows you to have up to eight windows open at the 
same time, you can have all the files open for editing. That way, you can quickly 
switch between them just by choking inside the diflferent windows, instead of 
having to jump back and forth within one large file. You can also look at the 
difiFerent portions side by side by arranging the windows on the screen, using the 
Stack Windows or Tile Windows command in the Format menu. 

There is a better way to break up large programs into chunks: units. For 
example, you could place the definitions and routines in BIGJOB. DEF and 
BIGJOB. UTIL into a single unit, compile it, and use it with a uses statement. 
Likewise, you could turn BIGJOB.MENU, BIGJOB.EVENT, and BIGJOB. INIT 
into units. Chapter 8 gives more details on how to do this. 
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Output (Code) Files: The {$0 (file)} Directive 



When you compile a Turbo Pascal program to disk, the resulting code file adopts 
its name from the program header. For example, if your program header is 

prograi Banzai; 

then the code file created on the disk is called BANZAI. However, you can 
override that default and request a specific code file name using the {$0 (file)} 
directive. This defines the name of the output (machine code) file. If you 
changed your program to read 

prograi Banzai; 
{$0 MyNeatProgram} 

then a compile to disk produces a code file named MYNEATPROGRAM. 

You now know how to get Standard Pascal programs running on the Mac 
under Turbo Pascal. However, you can refer to Part II and Appendix A as your 
programs grow more complex. They oflFer more information on the special fea- 
tures that Turbo Pascal has to ofier. 

Of course, you don't want to stop with ''textbook" Pascal programs. You want 
to write Mac-style programs, programs that use menus and windows and 
graphics. The rest of Part I is designed to help you to do just that. Let's lay some 
groundwork in Chapter 6. 
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CHAPTER 



Harnessing the Full Power of Your Mac 



The Macintosh has some of the most sophisticated system software ever put 
on a microcomputer. It gives most larger computers a run for their money. To 
programmers, however, sophisticated usually means complex, and complex 
rarely means easy to program. Well discover whether that is true of the Mac in 
this chapter. We'll introduce you to the concepts behind the Mac, explore bit- 
mapped graphics, and explain the Toolbox and operating system tools and 
resources that are at your disposal. 



The Macintosh Philosophy 



The designers of the Macintosh had the stated goal of designing a ^'computer 
appliance," the microcomputer equivalent of a toaster — ^that is, a system that 
people with little computer experience or background could learn to use in a 
very short time. By this criterion, the Mac is a smashing success: It is, to date, 
the easiest computer for a naive user to learn. Most Mac software follows a 
standard user interface, or format, so the typical Mac user can start using new 
applications almost immediately. 

The use of a standard interface is enforced by Toolbox (ROM -based) and oper- 
ating system (RAM-based) routines that the Mac provides. Simply put, the 
obstacles to not using the Mac's routines are so great that most applications 
conform to them. However, the routines are so comprehensive and complex that 
the novice Mac programmer £aces a steep learning curve. 
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The basic Macintosh isn't terribly complex in terms of hardware. It has a 
68000 (or 68000-related) processor, a monochrome (black-on-white) bit-mapped 
screen, RAM memory ranging from 128K in the older Macs to over 4M in 
upgraded systems. Read Only Memory of either 64K or 128K, and some I/O 
hardware (serial ports, disk ports, and so forth). Fairly simple and straightfor- 
ward stufiF — until you look at what's in that ROM. 

The Mac pioneered four major microcomputer concepts: graphics-only dis- 
play, visual user interface, event-driven software, and extensive system software. 

Graphics-Only Display 



Until the Mac appeared, most computers had text-only display or let you choose 
between text and graphics. In both cases, the text display was a fixed font with 
predetermined resolution and size (typically 80 columns of text in a 25-line dis- 
play). 

The Mac doesn't have text-only display. Instead, everything is done with bit- 
mapped graphics, including all text display. Bit mapping simply means that the 
Mac screen is made up of a grid of bits, which make up the shapes — characters or 
figures — ^that appear on your display. It's explained further in the following 
pages. 

Because of bit mapping, writing and editing text on the Mac screen is more 
complex than on other micros. But it also means that you have tremendous flexi- 
bility in how that text is presented, in terms of size, style, and font design, and in 
mixing text with graphics. In addition, you can change any of these elements and 
redisplay them on screen coundess times. 

The Mac almost single-handedly spawned desktop publishing, although this 
function is rapidly being adapted to other systems. The ability to produce high 
quality documents with professional layouts used to be limited to companies that 
could aflFord to buy or use very expensive typesetting equipment. Now, anyone 
with a Mac can lay out and prepare slick documents. With access to a laser 
printer (or even some of the newer typesetting machines), you can produce hard 
copy that is comparable to copy bom a professional printer. 

Visual User Interfaces 



The second Mac design concept is the visual user interface based on menus, 
icons, windows, and a mouse as the input device. The concept itself isn't new. 
Neither is the interface unique to the Mac, since other microcomputers now 
ofier similar approaches. However, the Mac represents the first (and still the 
best) attempt to make such a user interfece available at a relatively low price. 
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Event-Driven Software 



The third major concept is event-driven software. As with the first two concepts, 
this concept did not originate with the Mac, but it was the first micro to exten- 
sively use it and, in fact, to make it a requirement for just about any appUcation. 

At the core of most Mac applications is an event loop that polls the Mac operat- 
ing system for events (mouse clicks, keys pressed, menu selections, window 
operations, and the like), then calls the appropriate internal routines to handle 
those events. The goal is what Mac designers call modeless programs, where 
most functions are available at any point. In modal programs, you have to enter 
specific modes (insert mode, delete mode, command mode) to be able to per- 
form the corresponding functions. 

Extensive System Software 



The fourth major concept is extensive system software (in ROM and on disk). The 
software supports the user interface and event-driven programming approach, 
and makes them standard for all applications. Earlier microcomputers had some 
software (usually the Basic Input/Output System or BIOS) in ROM, but this was 
usually on the order of 8K to 16K of ROM and supported rather primitive screen 
and disk I/O functions. The original Mac came with 64K of ROM (increased in 
later versions). 

The current Mac ROM supports numerous and complex functions. The Mac 
operating system provides a large set of standard functions and procedures, and 
it also maintains an event queue that keeps track of events that applications must 
deal with. 

The irony of all this is that the original Macintosh was sorely crippled due to 
hardware limitations, with no means of adding memory and no expansion slots or 
hardware bus. However, Apple has learned some lessons since then, and the 
current Macintosh Plus represents a far better environment for the Mac software 
concepts. Future Mac products will undoubtedly continue to improve upon that. 

Bit-Mapped Graphics 



The standard Mac interface is a bit-mapped graphics display consisting of 342 
lines, each line containing 512 pixels (picture elements, that is, dots). There are 
175,104 pixels in all, each of which can be black or white. The display is called 
bit-mapped because each pixel on the screen corresponds to a single bit (0 or 1) 
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in memory (RAM). For that reason, this type of display is also referred to as 
memory-mapped. 

Since there are 8 bits in a byte, simple math shows that the screen takes up 
21,888 bytes (or about 21K) of memory. By changing the values of those bytes, 
you change what's on the screen; it's that simple. To draw a line (or other shape), 
your program simply goes to the appropriate locations in memory and sets the 
appropriate bits to 0 or 1. What's more, the Mac has an extensive and powerful 
graphics library (QuickDraw) to make using these graphics even easier. 

However, manipulating a bit-mapped display can be complicated and tedious. 
To draw a character on the screen, you can't just poke an ASCII value into a byte 
somewhere, as you can on most other microcomputers. Instead, the character 
must be drawn bit by bit. A programmer can simplify matters somewhat by 
maintaining a character font somewhere, with a bit map for each possible charac- 
ter, but there are still issues of font size and style, of whether the font is letter- 
spaced proportionally (that is, characters are spaced according to their width), 
and so on. In addition, adding, deleting, and modifying text can get very elabo- 
rate. Fortunately, the Mac comes with a large set of routines for text display, 
manipulation, and editing. By using these, you don't have to reinvent the wheel. 

The real bonus of bit-mapped graphics is the marriage of graphics and text, 
and the ability to manipulate both on the same display. You can readily mix 
pictures and words, allowing diagrams to be inserted in documents and explana- 
tions in schematics. On the Mac, you can draw a picture, then paste it into a 
letter or report. And, of course, it is this flexibility that has made the Mac pre- 
eminent in the field of desktop publishing. 

The Mac User Interface 



Three interrelated ideas form the nucleus of the Mac user interface: 

• the mouse as an input device 

• using icons, menus, windows, and other (mostly) graphic devices for informa- 
tion and command selection 

• an orientation toward modeless environments 

The mouse may well be the most controversial of the three ideas. Debates 
continue to rage over whether it aids or hinders user interaction. For that mat- 
ter, users argue over whether the mouse should have one, two, or three buttons. 
A graphics-based, visual system does require some sort of pointing device, and 
the mouse works as well as or better than most. 

The second idea, simply put, is that graphics convey more information than 
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text (or, to abuse an old cliche, a picture is worth IK words). By presenting files 
as icons on a desktop, the selection and manipulation of files with the mouse is 
fairly self-evident, especially for novice users. Likewise, the pull-down menu 
makes it easy to view and choose available commands and options vdthout having 
to remember obscure command names or wade through multiple levels of text- 
based menus. Within applications themselves, there tends to be a heavy orienta- 
tion towards presenting data in graphic (rather than textual or numeric) form. 

The third idea assumes that it is ideal to have as many options as possible 
available to the user at any given time. Rather than have multiple levels and 
numerous loads, the Mac attempts to keep all commands on one level, though 
some commands or options may be disabled when appropriate. 

For example, the File menu in Turbo Pascal is always on the menu bar, as are 
the Edit, Search, Format, Font, Compile, and Transfer menus. However, not all 
commands in those menus are available at all times. The user is spared the 
tedium of keeping track of which mode he or she is in and the commands that 
exist (or don't exist) on that level. 



Event-Driven Programming 



The basic structure of most Macintosh applications is nearly identical, with a 
main body that looks something like this: 

begin 

Initialize; 
repeat 
SystemTask; 

if GetNextEvent(eventMask/theEvent) then 
HandleEvent(theEvent) 
until Done; 
Cleanup 
end. 

The program does its setup with the user-defined routine Initialize, It then 
enters a loop that continues until some condition (such as the user selecting the 
command Quit in a menu) causes it to set the Boolean flag Done to True. 

Within that loop, it performs two major tasks. First, it calls SystemTask (a 
Toolbox routine), which allows the Mac operating system to update any desk 
accessories that might be in use. Second, it calls GetNextEvent (another Toolbox 
routine) to see if any events have occurred. If any have, it calls HandleEvent, 
which is a user-defined routine that handles all the difiFerent events that might 
occur. Such events include key presses; selection of menu items; mouse clicks; 
windows being opened, closed, uncovered, or resized; and similar occurrences. 

When the program is done, it calls the user-defined routine CfeanC/p, which 
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takes care of any necessary tidying up. (This last task depends on the appUcation 
itself; usually, it means freeing allocations made in memory by the application 
back to the system and similar tasks.) 

This is quite different from most interactive computer software developed 
before the Macintosh. In other systems, the program usually sits and waits for 
the user to type in a specific command, then handles it. The programs tend to be 
modal, with different levels and modes, each having its own command set. The 
commands themselves are usually context-sensitive, with the same command (or 
at least command sequence, that is, a given letter or word) holding different 
meanings depending upon the current mode or state. 

In a Macintosh application, most commands are usually available and applica- 
ble. About the only time you can't use a given command is when there is nothing 
to use it on; for example, if you haven't opened a window to edit text, then most 
of the editing commands don't make any sense. In the modeless approach, how- 
ever, those edit commands can work on any text window, whether it be one your 
apphcation has opened, or one opened by a desk accessory. 

Event-driven programming takes some getting used to, but once you under- 
stand how it works and have seen a number of examples using it, it becomes 
straightforward and easy to apply to different situations. In Macintosh applica- 
tions, the format is so standard that you can move from program to program and 
see almost identical code in the main procedures and immediate supporting 
routines (such as HandleEvent), 

Toolbox and Operating System Routines 



To make the Mac user interface standard in most applications, Apple designed it 
to be easy to follow and difficult to deviate from. This was particularly true of the 
original Mac, which had 128K of RAM (much of which was consumed by the 
video display and the operating system) and 64K of ROM (the Toolbox). Since 
graphic applications tend to be memory intensive (that is, they need lots of 
RAM), most developers on the Mac just didn't have the extra memory to do 
things their way. So they were forced to use the extensive libraries of procedures 
and fianctions found in the Toolbox ROM and in the operating system itself 

The resulting uniformity in Mac software allows most Mac owners to use a 
brand-new software package with little or no reference to the manual. 

The Toolbox and operating system (OS) routines are organized into related 
groups, often labeled managers or packages (not unlike units, which you'll learn 
about in Chapter 7). A list follows with the routine name and a brief description 
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of what the routines and data types within each allow you to handle. The list is 
arranged more or less in order of what you need to learn before moving on to the 
next item, although some concepts are best understood as a group. 

Resource Manager: Files can contain resources, such as definitions of menus, 
windows, icons, and text strings, as well as chunks of code. These routines let 
you access, identify, and manipulate resources within a given file. 

QuickDraw: The heart of the Macintosh, this package contains the basic graphics 
routines used by the other managers and packages. 

Font Manager: You can display text on the Mac in different /ont5, that is, with 
differently designed character sets. This package helps you (and QuickDraw) 
load or unload specific fonts from the disk for text display. 

Toolbox Event Manager: These routines form the foundation for event-driven 
programming. Besides GetNextEvent, this package also allows for direct polling 
of the mouse, the keyboard, and the system clock. 

Window Manager: The Mac allows you to set up multiple windows, each acting 
like its own screen. This package helps you create, move, modify, update, and 
delete windows. 

Control Manager: Mac software often uses graphic controls — buttons, dials, 
scroll bars, switches, and check boxes — for selection and display. These rou- 
tines allow you to select and use predefined controls and to design your own. 

Menu Manager: A menu bar across the top of the screen shows you the pull- 
down menu options; selecting a particular menu allows you to examine com- 
mands and pick a specific one. This package lets you create, manipulate, and 
interrogate your menus (that is, go into the menu commands and find out how 
they were set up). 

TextEdit: TextEdit helps you edit text by providing routines to insert, delete, 
select, and scroll text within a window, and to transfer text from one location (or 
window) to another. 

Dialog Manager: When a Mac application wants to bring something to the user's 
attention, it usually does so via a dialog box. This is a window with some informa- 
tion (graphics and/or text) in it and with one or more ways to enter a command 
(buttons, switches, text or numeric entry, and so on). This package helps you de- 
sign and present dialog boxes, and to correctly interpret a user s response to it. 

Desk Manager: Most applications maintain the Apple menu option (the one on 
the far left with the Apple logo instead of a name), which contains special pro- 
grams known as desk accessories (covered in Chapter 8). Desk accessories can be 
open and running even while your program is running, so you need to be able to 
accept and receive their messages. Desk Manager routines allow you to detect 
and handle actions required by the desk accessory. 
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Scrap Manager: This package helps you transfer data (such as text) between 
appUcations or between locations in a given application. 

Toolbox Utilities: This is a collection of miscellaneous routines, including (but not 
limited to) fixed-point math; string, byte, and bit, including logical operations on 
long integers; and miscellaneous graphics-oriented routines. 

Package Manager: A package is a set of routines and data structures stored on 
disk (as resources in the SYSTEM file) and loaded into RAM as needed. Six 
diflPerent packages are available through the Package Manager: 

• the Binary- Decimal Conversion Package (conversions between decimal 
strings and internal binary representations); 

• the International Utilities Package (diflFerent languages' character sets); 

• the Standard File Package (selecting files for I/O); 

• the Disk Initialization Package (formatting blank disks); 

• the Floating-Point Arithmetic Package (for IEEE-standard floating-point 
math); 

• the Transcendental Functions Package (for floating-point routines, such as trig- 
onometric functions, logs, and financial fiinctions). 

Memory Manager: The Mac has a complex way to allocate relocatable blocks of 
memory so that dynamic garbage collection can occur without disturbing any 
program currently executing. When used properly, these routines ensure that 
memory is correctly allocated or recovered. 

Segment Loader: Programs that are unwieldy because of size can be divided up 
into segments; each segment can be up to 32K in size. The Segment Loader 
governs the execution, segment loading, and termination of an application. 

Operating System Event Manager: The Toolbox Event Manager allows you to 
query the operating system for events; the routines in this manager allow you to 
work directly with the event queue that the operating system maintains. 

File Manager: This manager handles just about everything having to do with 
files, from high-level volume management to low-level file I/O. 

Printing Manager: The Macintosh presents some special challenges in capturing 
what's on the screen or in a text file out to a printer. In conjunction with the 
printer drivers found on your system disk, these routines allow you to print the 
graphic images created by Mac software. 

Device Manager: This package is a general version of the File and Printing 
Managers. It lets you work with custom device drivers and perform I/O with 
those devices. 
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Disk Driver, Sound Driver, Serial Drivers: These routines give your software 
control of the corresponding hardware items (floppy drives, DAC, RS422 ports) 
on the Mac. 

AppleTalk Manager: Apple has defined a simple local-area network (LAN) for 
Apple products known as AppleTalk. This collection of data structures and rou- 
tines allows you to communicate over that network. 

Vertical Retrace Manager: This allows you to create interrupt-driven tasks that 
are called every so many ticks, where a tick is one-sixtieth of a second and corre- 
sponds to how often a vertical retrace interrupt occurs, A vertical retrace is one 
cycle of redrawing the screen, and you can use the cycle as a timer to trigger a 
routine. 

System Error Handler: The one routine in this package, SysError, brings up the 
system error dialog box (with the bomb in it). Not for casual use. 

Operating System Utilities: Another collection of assorted handy routines, 
including procedures and functions for pointer and handle manipulation, string 
comparison, date and time operations, parameter RAM operations, and other 
utilities. 

With the proper use of these routines, your application will fit into the stan- 
dard Macintosh mold. A regular Mac user will then be able to easily start it up 
and use it. 



Further Reading 



If you want to do any serious programming on the Mac, there are a few standard 
reference works: 

• Inside Macintosh, written by a team at Apple and published in four volumes 
(softbound) by Addison- Wesley, documents the hundreds of routines available 
through the Toolbox and operating system. It is also available hardbound. 

• Macintosh Revealed, volumes 1 and 2, written by Stephen Chernicojff and 
pubhshed by Hayden (under its Apple Press line of books). 

• MacTutor is a magazine dedicated to programming on the Mac; each issue 
usually contains lots of short, working samples of code (call (714) 630-3730). 

• How to Write a Macintosh Application, written by Scott Knaster and pub- 
lished by Hayden. 

• Macintosh Technical Notes, published by Apple Computer, Inc. 
Now, let's go on to the libraries — ^units — ^that the Mac provides. 
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CHAPTER 



Units and Other Mysteries 



In Chapter 5, you learned how to adapt standard Pascal programs for use by 
Turbo Pascal on the Mac. What about non-standard programming — ^more specifi- 
cally, Mac-style programming? Before anything else, you have to understand the 
concept of units and of external and inline procedures and functions. 

This chapter explains what a unit is, how you use it, and what predefined units 
are available for your use. You'll also learn how to set up and use external and 
inline procedures and functions. Among the other mysteries we delve into here 
are traps and assembly-language routines. 

Whafs a Unity Anytvay? 



Turbo Pascal gives you access to a tremendous number of predefined constants, 
data types, variables, procedures, and functions. Some are specific to Turbo Pas- 
cal; others are specific to the Macintosh. There are literally hundreds of them, 
but you hardly ever use them all in a given program. Because of their number, 
they are split up into related groups called units. You can then use only the units 
your program needs. 

A unit is a collection of constants, data types, variables, procedures, and func- 
tions. Each unit is almost like a separate Pascal program. It can even have a main 
body that is called before your program starts and is used to do whatever initial- 
ization is necessary. In short, a unit is a library of declarations that you can pull 
into your program and use. 
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AH the declarations within a unit are usually related to one another. For exam- 
ple, the QuickDraw unit has all the declarations for QuickDraw routines on the 
Mac. 

When a program uses a unit, all its declarations become available, just as if 
they had been defined within the program itself. 

A unit consists of two parts: the interface and the implementation. The inter- 
face is the ^public** part of the unit. It contains constants, data types, and vari- 
ables. It also has a list of procedure and function headers. Any program using the 
unit can use all these items. In other words, the program uses them as if they 
had been declared within the program itself 

The implementation is the ''private" section of the unit. The bodies of the 
procedures and functions declared in the interface reside here. Additional con- 
stants, data types, and variables can be declared and used within the implemen- 
tation. Likewise, additional procedures and functions may exist in this section. 
However, all these items are "invisible'* to the program using the unit; the pro- 
gram doesn't know that they exist and can't reference or call them. However, 
these hidden items can be (and usually are) used by the "visible" procedures and 
functions, that is, those routines whose headers appear in the interface. Chapter 
8 explains more about both these sections. 

The units your program uses have already been compiled; that is, they are 
stored as machine code, not as Pascal source code. They are not Include files. 
Even the interface section is stored in the special binary symbol table format that 
Turbo Pascal uses. Furthermore, all the standard units (listed in the next para- 
graph) are stored in the Turbo Pascal compiler/editor file and are loaded into 
memory along with Turbo Pascal itself 

As a result, using a unit or several units adds very little time (typically less 
than a second) to your program's compilation time. If the units are being loaded 
in from a separate disk file, a few additional seconds may be required because of 
the time it takes to read from the disk. 

Turbo Pascal provides 16 standard units for your use. Five of them — PasSys- 
tem, FaslnOuty PasConsoh, PasPrinter, and SANE — are known as the Pascal 
Run-time Support units and deal specifically with Turbo Pascal. The other 11 
units — MemTypes, QuickDraw, Oslntf, Toollntf, Packlntf, MacPHnt, FixMath, 
Graj3D, AppleTalk, Speechlntf, and SCS/Znt/^allow access to the full range of 
Macintosh Toolbox and operating system routines, including support for 
AppkTalk, MacinTalk, and the SCSI hard disk port. 

NOTE: In Turbo Pascal, each unit is assigned a specific unit number for iden- 
tification purposes. You don't really need to know these numbers. Just be aware 
that negative numbers are reserved for the standard units and for assignment by 
the UNITMOVER; positive numbers are available for any units you create. 
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How Are Units Used? 



To use a specific unit or collection of units, you place a uses-clause at the start of 
your program. The uses-clause consists of the keyword uses, followed by a Hst of 
the unit names you want to use, separated by commas: 

prograi MyProg; 

uses thisDnit/thatUnitftheOtherUnit; 

When the compiler sees this uses-clause, it adds the interface information in 
each unit to the symbol table and links the machine code produced by the imple- 
mentation to the program itself. 

The units are added to the symbol table in the order given; this ordering can 
be important when one unit uses another unit. For example, if thisUnit used 
thatUnit, the uses-clause would have to be: 

uses thatUnit, thisUnit, theOtherDnit; 
or 

uses thatUnit/theOtherUnit,thisDnit; 

In short, a unit must be listed after any units it uses. 

If you don't put a uses-clause in your program. Turbo Pascal links in three 
Pascal Run-time Support units anyway: PasSystem, PasInOut, and PasConsole» 
These provide some of the standard Pascal routines, a number of Turbo-Pascal 
specific routines, and also a model Pascal environment (complete with an 80X25 
screen, cursor-control and printer routines, and so on). 

What if you don't want some or all of these run-time units? You tell Turbo 
Pascal not to use them by placing the {$U-} option at the start of your program; 
only the PasSystem unit will be linked in. Any additional units you want must be 
explicitly requested with the uses-clause. For example, if you are writing a Mac- 
style application and don't want to use ihe PasConsole unit (since you don't need 
it), your program might look like this: 

prograa MyMacProg; 

{$U-> { don't autoKiatically use the run-time stuff > 
uses PasInOut/MemTypes, QuickDraw, OSIntf, 
ToolIntfrMacPrint/Packlntf ; 

This program does use one of the run-time units: PasInOut. However, since 
youVe put the {$U-} option in, you have to explicitly request the unit to use it. 
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Pascal Run-time Support Units 



Turbo Pascal provides a set of routines that make your Macintosh act Uke a stan- 
dard terminal, allowing you to read from the keyboard and write to the screen 
without all the tedious mucking about that the Mac usually requires of you. 
These routines also let you do conversions, Pascal-style dynamic memory alloca- 
tion, Pascal-style file I/O, and so on. 

Turbo Pascal uses three units — PasSystem, PasInOut, and PasConsole — to do 
all this. Two other units — PasPrinter and SANE — ^are provided for additional 
support. Here's a brief description of each unit, with its name and a listing of any 
units it might require. Appendix D lists the interface sections of these units. 

PasSystem 
Units used: none 

PasSystem implements the low-level support routines used by most programs, 
including Longint math, conversion between Real and Integer data types, string 
and set handling, dynamic memory allocation, and byte-oriented procedures. It 
is linked into every program, even if you use the {$U-} compiler option. (It's 
the only unit that doesn't have an interface listing in Appendix D.) 

PasInOut 

Units used: none 

PasInOut implements the standard Pascal I/O routines (Rearf, ReadLn, Write, 
WriteLn, Reset, Rewrite, and so on), as well as the Turbo-Pascal specific ones 
(Close, Seek, Rename, Erase, and so forth). It also does all I/O and range-error 
checking. If you look at the interface fisting in Appendix D, you'll find that there 
is very little you can use directly; instead, the compiler makes calls to specific 
hidden routines in the implementation. 

PasConsole 

Units used: PasInOut 

PasConsole is the unit that makes it easy to write textbook Pascal programs. It 
creates a window that emulates a terminal screen 80 characters wide by 25 lines 
deep. When this unit is used by a program or unit, any calls to Read or ReadLn 
without a file variable are made from the keyboard and automatically echoed to 
this window; likewise, any calls to Write or WriteLn without a file variable write 
to that window. A number of cursor- and screen-control routines are available: 
ClearScreen, ClearEOL, InsertLine, DeleteLine, and GoToXY. The functions 
KeyPressed and ReadChar are there, too, as are the file variables Input and 
Output. This unit also creates a new device ('Console:') that can be assigned to 
any file of type Text. The user can then send output to the screen (instead of to a 
disk file). 
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PasFHnter 

Units used: PasInOut 

PasPrinter declares the text-file variable Printer and connects it to a device 
driver that (you guessed it) allows you to send standard Pascal output to the 
printer using Write and WriteLn, For example, having included PasPrinter in 
your program, you could do the following: 

Write(Printer,'The sum of ',K:A,' and ',B:A,' is '); 
C := R + B; 
WriteLn(Printer,C:fl) ; 

Like PasConsole, this unit creates a new device ('Printer:') which can be 
assigned to any file of type Text. The user can then send output to the printer 
(instead of to a disk file). 

SANE 

Units used: none 

The SANE unit implements the Standard Apple Numeric Environment 
(SANE). SANE is the basis for all floating-point mathematical calculations per- 
formed by Turbo Pascal. Programmers who are interested in using SANE fea- 
tures not directly supported by Turbo Pascal can access these features through 
the SANE unit. For detailed instructions about SANE, see Chapter 26 and the 
Apple Numerics Manual. 

Macintosh Interface Units 



The Macintosh is a complex, sophisticated microcomputer. Some of its power 
comes from the built-in procedures and functions in the 64K or 128K of ROM 
and the SYSTEM file on disk. These routines are documented in Inside Macin- 
tosh , which breaks up the routines into a series of managers or packages: 
resources, QuickDraw (graphics), fonts, events, windows, controls, menus, 
TextEdit (text-editing), dialog boxes, and so on. In fact, you can think of these 
managers as units built into the Mac itself 

The Macintosh Interface units that Turbo Pascal provides allow you to use 
these Mac routines. Some of the units encompass several Mac managers or pack- 
ages. This is to make things more manageable; otherwise, you might need 20 to 
30 diflFerent units. Appendix D lists the interface sections of these units. 

As with the Run-time Support units above, a brief description of each unit is 
given, along with a list of the units it uses. Also, the insicfe Macintosh chapters 
that you can refer to are noted; the first number is the volume number, the 
second is the chapter number. 
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MemTypes 

Units used: none 

Chapters: "Mac Memory Management** (vol. I, chap. 3) 

MemTypes defines special Mac data types, such as SignedByte, Ptr, Handky 
and Str25S, That's all it does; there are no constants, variables, or routines 
defined. It is used by every unit in this list and so must be included in any Mac- 
style applications. 

QuickDraw 

Units used: MemTypes 

Chapters: **QuickDraw* (1-6) 

QuickDraw is a Macintosh graphics package that lets you perform complex 
graphic operations quickly and easily. This unit defines all the constants, types, 
variables, procedures, and functions needed to use QuickDraw. Since Quick- 
Draw resides entirely in ROM and uses standard Pascal parameter-passing con- 
ventions, the routines are all inline (see next item), and the unit itself contains no 
actual code. 

OSIntf 

Units used: MemTypes, QuickDraw 

Chapters: "Memory Manager" (II-l), "Segment Loader** (II-2), "OS Event 
Manager" (II-3), "File Manager" (II-4), "Device Manager" (II-6), "Disk Driver" 
(II-7), "Sound Driver" (II-8), "Serial Drivers" (II-9), "Vertical Retrace Manager" 
(II-U), "System Error Handler" (11-12), "OS Utilities" (11-13) 

The Macintosh operating system (Mac OS) is at the lowest level of Macintosh 
operations. It performs basic tasks such as input/output, memory management, 
and interrupt handling. Many of the Toolbox procedures and functions call Mac 
OS routines to support their operations. The OSIntf unit declares the Pascal 
interface to the Mac OS, naming the many constants, data types, variables, and 
routines. Since few of the Mac OS routines abide by Pascal conventions, inline 
code can't be used; instead, the unit itself provides the "glue," consisting of var- 
ious additional external assembly-language routines. OSIntf is easily the largest 
of the interface units. 

Toollntf 

Units used: MemTypes, QuickDraw, OSIntf 

Chapters: "Resource Manager" (1-5), "Font Manager" (1-7), "Toolbox Event 
Manager" (1-8), "Window Manager" (1-9), "Control Manager" (I-IO), "Menu Man- 
ager" (I-U), "TextEdit" (1-12), "Dialog Manager" (1-13), "Desk Manager" (1-14), 
"Scrap Manager" (1-15), "Toolbox Utilities" (1-16) 

The Toolbox implements the Macintosh's user interface features: windows, 
menus, controls, dialog boxes, text editing commands, and so on. This powerful 
set of tools helps you create sophisticated applications with comparatively little 
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effort. A few of these routines need to be linked with routines via the Toollntf 
unit; most, though, can be taken care of with inline calls. 

Packlntf 

Units used: MemTypes, QuickDraw, OSIntf, Toollntf 

Chapters: "Package Manager" (1-17), ^'Binary-Decimal Conversion Package'' 
(1-18), "International Utilities Package" (1-19), "Standard File Package" (1-20), 
*Disk Initialization Package" (11-14) 

Packages are sets of data structures and routines that are stored as resources in 
the SYSTEM file and brought into memory only when needed. They serve as 
extensions to the Toolbox and Mac OS; the most useful (and most commonly 
used) is the Standard File Package, which brings up the standard Mac dialog box 
to open files or select a file name for output. Packlntf provides the interface to 
those packages. 

MacPrint 

Units used: MemTypes, QuickDraw, OSIntf, Toollntf 
Chapters: **Printing Manager" (II-5) 

The MacPrint unit provides access to the Macintosh Printing Manager. The 
Printing Manager is a set of RAM -based data types and routines that allow you to 
use standard QuickDraw routines to print text or graphics on a printer. These 
provide a device-independent interface to printer drivers, which enable you to 
print on a specific device (Image Writer, LaserWriter, and so on). One (or more) 
of these printer drivers — usually found in the SYSTEM folder — must be avail- 
able in order to use this package. 

FixMath 

Units used: MemTypes 
Chapters: none 

The FixMath unit is a collection of types and functions that implement fixed- 
point real numbers. This unit is very useful for applications that require real 
numbers but don't need the accuracy of floating-point math. Fixed-point opera- 
tions run much faster than regular floating point, so you can choose to sacrifice 
precision for increased speed. 

GrafiD 

Units used: MemTypes, QuickDraw, FixMath 
Chapters: none 

GrafiD is a RAM-based, three-dimensional graphics package that sits on top 
of QuickDraw, It implements 3-D GrafPorts and provides a complete set of 3-D 
operations, including rotation, translation, scaling, and clipping. 
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AppleTalk 

Units used: MemTypes, QuickDraw, OSIntf 

Chapters: ''AppleTalk Manager** (11-10), (see also Inside AppleTalk) 

AppleTalk is the Macintosh local-area network — that is, the means by which 
you connect a group of Macintoshes with printers, disks, other devices, and each 
other. The AppleTalk Manager is used to communicate with devices connected 
to an AppleTalk network. AppleTalk is implemented as two RAM-based device 
drivers, .ATP and .MPP, and the AppleTalk unit declares the necessary Pascal 
types and procedures for using them. 

The drivers are in the resource branch of the file ABPACKAGE on the distri- 
bution disk. If an application will use AppleTalk, then these drivers should either 
be placed in the SYSTEM file or in the application itself The latter is preferable, 
since you can then move the application from disk to disk (and system to system) 
without having to worry about whether or not the drivers are there. To add the 
drivers to your file, put the following Hues in your RMAKER resource file (see 
Chapter 6 and Appendix C for more details on RMAKER): 

Type atpl = GNRL 

iD (lb) 

.R 

ABPackage atpl D 
The atpl resource type must be in lowercase letters. 

NOTE: The AppleTalk drivers may not be redistributed. They are licensed by 
Borland International and are for your personal use only. 

Speechlntf 

Units used: MemTypes 
Chapters: none 

The Speechlntf unit provides an interface to MacinTalk, a speech synthesizer 
that runs under Mac OS as a driver. In real time, MacinTalk converts an ASCII 
string of phonetic codes into synthetic speech. MadnTalk uses a special program, 
READER, to convert English text into the phonetic codes used by MacinTalk. 
The MacinTalk driver must he in the SYSTEM folder in order for your program 
to work. 

More information on Speechlntf is contained in the MacinTalk Toolkit docu- 
mentation, in the December 1985 Mac Softvmre Supplement Document from 
Apple. 

NOTE: MacinTalk may not be redistributed. It is licensed by Borland Inter- 
national and is for your personal use only. 



64 



Turbo Pascal for the Macintosh 



SCSllntf 

Units used: MemTypes 

Chapters: ^The SCSI Manager'' (4-31) 

The SCSllntf unit provides access to the Small Computer Standard Interface 
(SCSI) port found on several models of the Macintosh. It allows you to determine 
what devices are connected to the SCSI port and to communicate with them. 

Calling Assembly-Language Routines 



Yes, Turbo Pascal allows you to link in external subroutines written in 68000 
assembly language. Full details, including how to pass parameters and return 
function values, can be found in Chapter 27. Following is a quick explanation of 
how to call assembly-language routines. 

Before using an external procedure or function in a program, you must define 
it. To define it, you write its procedure or function header, followed by the 
keyword external: 

procedure LowToUp(var Str : string); external; 

function RotLeft(var L : Longint; D : Integer) : Longint; external; 

Note that there is no body to the procedure or function, just the header state- 
ment. 

The procedure/function headers go wherever a regular procedure or function 
can go. If they're in a program, you can place them anywhere. If they're in a 
unit, they can go either in the interface (if you want the user to be able to call 
them) or in the implementation (if you don't). 

Next, write the appropriate routines, using Apple's Macintosh Development 
System (MDS) or an MDS-compatible assembler. The resulting .REL file must 
be in MDS format (either version 1 or version 2). Refer to Chapter 27 for details 
on how Turbo Pascal passes parameters to external routines, and how external 
functions should pass values back. 

Finally, you must tell the compiler what file to link to it, using the {$L} com- 
piler directive. If you had assembled your assembly-language routines into a file 
called MYSTUFF.REL, then you'd put the following directive somewhere in 
your program: 

{$L MyStuff .RED 

This directive can appear anywhere before the begin of the main body of your 
program, or the begin of the initialization section in your unit (if you're writing 
your own unit). 
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when you compile your program, Turbo Pascal goes to MYSTUFF.REL, 
copies the machine code into your application file, and creates the necessary 
links. 



Inline Code and Traps 



In addition to external assembly-language subroutines, Turbo Pascal also allows 
you to write internal machine-language code for your program. The key phrase 
here is machine language, since the actual inline code is written as numeric 
constants (preferably, though not necessarily, hexadecimal). The format for defin- 
ing inline code is 

<proc/func declaration>; inlitte <integer constant(s)>; 

The constants are of type Integer, not of type Longlnt. If more than one con- 
stant is used, the constants are separated by commas. So, for example, you could 
write the following: 

procedure TextFace(Face : Style); 
inline $2D5F, $1010, $BFDD, $Aflflfl; 

This code would disassemble to the following 68000 code: 

MOVEA.L (A7)+,A0 

H07E.B (AO),DQ 

MOVE.W DD,(A7)- 

DS.W $Aflflfl ; trap to ROM routine 

The Mac Toolbox implements most of its routines as traps. A trap is a special 
instruction that causes the CPU to stop what it's doing and attend to the trap. On 
the 68000, for example, any instruction with the bit pattern $Axxx causes a trap. 
The 68000 then calls a special trap-handling routine, which decodes the rest of 
the instruction and decides what to do about it. On the Macintosh, that trap 
handler looks at the rest of the bits and calls the appropriate ROM or RAM 
routine before returning to the program where the trap occurred. 

Confused? Just think of traps as do-it-yourself machine code instructions. If 
you'll look through the unit interface listings for, say, QuickDraw, youll see that 
most of the procedures and functions are inline calls to traps. (The example 
above, in fact, was taken from QuickDraw.) 

One last bit of information about inline calls. An inline procedure or function 
is not set up as a separate subroutine, so there is no JSR (jump to subroutine) to 
an inline routine. Instead, whenever a call to an inline routine occurs, the com- 
piler sets everything up as if it were going to make a subroutine call (pushing 
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parameters and the return address on the stack). It then inserts the actual inline 
code right after that. Say, for example, that you wrote the following code: 

if BFlag then 

TextFace(Cbold]) { use bold type > 
else TextFace([]); i use plain type > 

At each call to TextFace, the compiler would generate the code to push the 
parameter and return address onto the stack, then insert the four words found 
above ($205F, $1010, $3F00, $A888). 

Now that you Ve been introduced to units, you have two options as to where to 
go next. If you're interested in writing your own units, go on to Chapter 8. If, 
instead, you want to start writing Mac-style programs, skip to Chapter 9. How- 
ever, you should read through Chapter 8 at some time. 
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CHAPTER 



Writing Your Own Units 



In Chapter 7, you learned how useful units could be. They provide an efficient 
way to organize groups of data structures and subroutines for use in diflFerent 
programs. In this chapter, youll learn how to write your own units. You'll be 
shown the general structure of a unit and its interface and implementation por- 
tions, as well as initialization and compilation. Also included are a few program 
examples. 



A Quick Review of Units 



A unit is a collection of constants, data types, variables, procedures, and func- 
tions. Like a complete Pascal program, it can even have a "main body" that is 
called before your program starts and does whatever initialization is necessary. 
In short, it's a Hbrary of declarations that you can pull into your program and use. 
All the program elements in a unit are usually related to one another, so that a 
unit tends to solve a set of problems or offer a set of capabilities. When a program 
uses a unit, all its declarations become available, just as if they had been defined 
within the program itself. 

A unit consists of two parts: interface and implementation. The interface is the 
actual collection of declarations that can be read by the program. This can 
include constants, data types, variables, and headers for procedures and func- 
tions. The implementation is where the bodies (the code) of the procedures and 
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functions declared in the interface actually reside. Additional constants and the 
like also can be declared and used within the implementation. These items, 
however, are not available for viewing by the program using the unit. 

Let's talk in more detail about how a unit is laid out and what the difierent 
sections do. 



A Unifs Structure 



As mentioned above, a unit has a structure not unlike that of a program, but with 
some significant diflFerences. Here's a unit, for example: 

unit <identifier>(unit #); 
interface 

uses <list of units>; -C optional > 

{ public declarations } 
inplenientation 

{ private declarations } 

{ procedures and functions } 
begin 

{ initialization code } 
end. 

The unit header starts with the reserved word unit, followed by the unit's 
name (an identifier), just as a program has a name. A unit number, in paren- 
theses, appears between the unit name and the semicolon terminating the 
header. This number — a positive 16-bit integer constant— should be difiFerent 
from any other unit number that your programs might use. 

The next item in a unit is the keyword interface. This signals the start of the 
interface section of the unit, that is, the section visible to any other units or 
programs that use this unit. 

A unit can use other units by specifying them in a uses-clause. If present, the 
uses-clause appears right after the keyword interface. Note that the general rule 
of a uses-clause still applies: If a unit named in a uses-clause uses other units, 
those units must also be named in the uses-clause, and their names must appear 
in the list before that of the unit using them. 

As with a program, if a unit does not include a {$U-} directive, the PasInOut 
and PasConsole units are automatically used by that unit. This further means, 
that a program using that unit would also have to use PasInOut and PasConsole, 
even though they may not be required. In general, if a unit does not require any 
of the functions provided by PasInOut and PasConsole, you should place a {$U-} 
directive in the beginning of the unit. 



70 



Turbo Pascal for the Macintosh 



Interface 



A unit provides a set of capabilities through procedures and functions — ^with 
supporting constants, data types, and variables — but it hides how those capabili- 
ties are actually implemented. It does this by breaking the unit into two sections: 
the interface and the implementation. 

The interface portion of a unit starts at the reserved word interface, which 
appears after the unit header, and it ends when the reserved word implementa- 
tion is encountered. The interface determines what is ''visible" to any program 
(or other unit) using that unit. In the unit interface, you can declare constants, 
data types, variables, procedures, and functions. As with a program, these can 
be arranged in any order, and sections can repeat themselves (for example, type 
. . . var . . . <procs> . . . const . . . type . . . const . . . var). 

The procedures and functions that are visible to any program using the unit 
are declared here, but their actual bodies — ^that is, implementations — ^are found 
in the implementation section. If the procedure (or function) is external, that 
keyword should appear in the interface, and no redeclaration of the procedure 
need occur in the implementation. If the procedure (or function) is inline, the 
machine code (list of integer constants) should appear in the interface section, 
and no redeclaration of the procedure should occur in the implementation. For- 
ward declarations are neither necessary nor allowed. The bodies of all the regu- 
lar procedures and functions are held in the implementation section, afler all the 
procedure and function headers have been listed in the interface section. 

Implementation 



The implementation section starts at the reserved word implementation. Every- 
thing declared in the interface portion is visible in the implementation: con- 
stants, types, variables, procedures, and functions. Furthermore, the implemen- 
tation can have additional declarations of its own, although these are not visible 
to any programs using the unit. 

If any procedures have been declared external, one or more {$L {.REL file)} 
directive(s) should appear before the begin marking the initiaUzation section. If 
there is no initialization section, then it can be anywhere before the final end of 
the unit. 

The normal procedures and functions declared in the interface — those that are 
neither external nor inline — must reappear in the implementation. The proce- 
dure/function header that appears in the interface should not appear in full in the 
implementation. Instead, just type in the keyword (procedure or function), fol- 
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lowed by the routine's name (identifier). The routine should then contain all its 
local declarations (labels, constants, types, variables, and nested procedures and 
functions), followed by the main body of the routine itseE Say the following 
declarations appear in the interface of your unit: 

procedure Swap(var VI, VE : Integer); 
function Max(Vl,VE : Integer) : Integer; 

The implementation should look like this: 

procedure Swap; 
var Temp : Integer; 
begin 

Temp := VI; VI := V5; VE := Temp 
end; { of proc Swap > 

function Max; 
begin 

if VI > VS then 
Max := VI 

else Max := VE 
end; { of func Max > 

Routines local to the implementation (that is, not declared in the inter&ce 
section) should have their complete procedure/function header intact. 



Initialization 



The entire implementation portion of the unit is normally bracketed within the 
reserved words implementation and end. However, if you put the reserved word 
begin before end with statements between the two, the resulting compound 
statement — ^looking very much like the main body of a program — becomes the 
initialization section of the unit. When a program using that unit is executed, the 
unit's initialization section is called before the program s main body is run. If the 
program uses more than one unit, each unit's initialization section is called (in 
the order specified in the program's uses statement) before the program's main 
body is executed. 

The initialization section is where you initialize any data structures (variables) 
that the unit uses or makes available (through the interface) to the program using 
it. You can use it to open files for the program's later use. For example, the 
runtime unit PasPrinter uses its initialization section to make all the calls to open 
(for output) the text file PRINTER, which you can then use in your program's 
Write and WriteLn statements. 
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Compiling a Unit 



You compile a unit using the same commands as when you compile a program. 
Normally, you'd compile a unit to disk to be able to use it with all your programs. 
However, if you have windows open for a unit and for a program that uses it, you 
can compile the unit to memory. The compiler always looks in memory before 
looking on disk, when searching for a unit named in a uses-clause. 

When you compile a unit to disk, the resulting library file adopts its name from 
the unit header. For example, if your unit header is: 

unit MyUnit(l); 

then the library file created on the disk is called MYUNIT. As with a program, 
you can override that default and request a specific file name using the {$0 
{filename)} directive. If you changed your unit to read: 

UEit MyOnit(l); 
{$0 MyLibrary) 

then a compile to disk produces a library file named MyLibrary. 

You may, in fact, compile several units to the same library file. Suppose you 
have two units and that both include a {$0 MyLibrary} directive. Every time 
you compile one of them, the newly compiled unit replaces the older version in 
the library file. 

The icon used for unit library files is different from the one used for compiled 
programs; it is an attache-case (or briefcase), which represents something you 
can ^'carry'' from program to program. Also, unlike a compiled program, if you 
double-click on a unit library file, the unit is not ''executed." Instead, the UNIT- 
MOVER is launched, and the library file is ''opened." Chapter 11 contains a 
complete explanation on using the UNITMOVER. 



Using Your Units 



Say youve written a unit called MYUNIT. PAS and compiled it to disk; the 
resulting code file is called MYUNIT. To use it in your program, you need to 
include two things: a {$U (filename)} directive to tell the compiler where to look 
for the unit and a uses statement to tell the compiler that you re using that unit. 
Your program might look like this: 

program MyProg; 
{$U MyUnit} 
uses HyUnit; 
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The unit name and the unit's code file name don't have to be the same. If you 
compile the unit with the directive {$0 MYUNITS. LIB} or change the code file 
name to that under the FINDER, then the {$U} directive in the program would 
have to read {$U MYUNITS. LIB}. 

Now, suppose you had compiled the units MyFirst and MySecond with the 
directive {$0 MyLibrary}. To use all three units, you would have to use two {$U} 
directives, both of them appearing before the uses-clause: 

prograa MyProg; 
{$U MyUnit} 
{$a MyLibrary} 

ases MyUnit/MyFirst, MySecond; 

Depending on your Macintosh system, there is a limit to the number of files 
you can specify with {$U} directives; it is at least ten for all systems, though. 

The section at this end of this chapter, ''UNITMOVER," explains how you can 
use this utility to simplify using units. Chapter 11 contains a complete explana- 
tion on using UNITMOVER. 



An Example 



OK, now let's write a small unit. We'll call it IntLib and put two simple integer 
routines, a procedure and a function, in it. Here's the unit: 

unit IntLib(l); 

interface 

procedure Swap(var I, J : Integer); 

function Max(I,J : Integer) : Integer; 
inpleaentation 

procedure Swap; 

var 

Temp : Integer; 
begin 

Temp :=I;I:=J;J:= Temp 
end; { of proc Swap > 
function Max; 
begin 

if I > J then 

Max := I 
else Max := J 
end; i of func Max } 
end. { of unit IntLib } 

Type this in, save it as the file INTLIB. PAS, then compile it to disk. The 
resulting unit code file is INTLIB. 
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Following is a program that uses this unit: 
prograa IntTest; 

{$U IntLib} { where to look for IntLib > 

uses IntLib; 

var 

A,B ; Integer; 

begin 

Write( 'Enter two Integer values: '); 

ReadLn(A,6) ; 

Swap(A,B); 

WriteLn('The raax is ',Max(A,B)); 
ReadLn; 

end. { of program IntTest } 



Units and Large Programs 



up until now, youVe probably thought of units only as libraries: collections of 
useful routines to be shared by several programs. However, units can do some- 
thing just as important: break a large program up into modules. In fact, units 
give Turbo Pascal many of the advantages of Modula-2 and other modular lan- 
guages, with few of their disadvantages. 

Two other aspects of Turbo Pascal make this function feasible: its tremendous 
speed in compiling and linking; and its ability to manage several code files simul- 
taneously, such as a program and several units. 

Typically, a large program is divided into units that group procedures by their 
function. For instance, an editor application could be divided into initialization, 
printing, reading and writing files, formatting, and so on. Also, there would be a 
**globar unit — one used by all other units, as well as the main program — ^that 
defines global constants, data types, variables, procedures, and functions. 

The compiled version of each unit is stored in a unit library file. Each unit 
references this file twice. First, it should reference it in a {$0 (filename)} direc- 
tive, since the compiled version of the unit should be put in that file. Second, 
that same file name would need to be the first {$U (filename)} directive, so that it 
could get the global declarations from the main unit (as well as any other unit it 
might happen to use). 

The skeleton program might look like this: 
prograi Editor; 

{$0 My Editor} { output file for application } 
{$T APPLMYED} { application type; creator ID « MYED } 

{$R Editor. Rsrc} { resource file for this application } 
{$D Editor. Lib} { library file with application's units } 

{$B+} { set bundle bit } 

{$U-} { disable automatic use of runtime units } 
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uses 

MemTypes, QuickDraw rOSIntf/ToolIntf,PackIntf,MacPriiit/ 

EditGlobals, 

Editlnit, 

EditPrint, 

EditReadrEditWrite, 

EditFormat; 

{ program's declarations, procedures, and functions } 

heqin 

{ main program } 
end. { of program Editor } 

One of the units — say, EditPrint — ^might look like this: 
unit EditPrint (3); 

{$0 Editor. Lib} { output file = library file } 

{$a Editor. Lib} { but uses units in libarary file as well } 

{$U-} { disable use of runtime units } 

interface 



uses 

MefflTypes,QuickDraw,OSIntf /Toollntf /Packlntf /MacPrint, 
EditGlobals; 

{ the rest of the interface } 
lipleientation 

{ implementation of the unit } 

end. { of unit EditPrint } 

A further refinement involves segmentation. Turbo Pascal allows you to break 
your program up into segments, that is, chunks of machine code, each one no 
larger than 32K bytes. The {$SH-} directive instructs Turbo Pascal to create a 
segmented code file, while the {$S (segname)} directive specifies into which 
segment a unit or a collection of subprograms (procedures and functions) will go. 

In the modified example below, the units are grouped into segments by their 
function. The Mac units, as well as EditGlobals, go into the ^'blank'* (or main) 
segment, so that they will always be resident with the main body of the program. 
The initialization unit {Editlnit) resides in a segment by itself, so that it can be 
disposed of once it has done its job. Likewise, the printing unit (EditPrint) is in 
its own segment, so that it takes up memory only when printing is going on. The 
modified section of the application looks like this: 

{$B+} 

<%S*} { enable segmentation } 

{$U-} 
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US6S 








{$S 




> 


MemTypes, QuickDraw /OSIntf/ToolIntf/Packlntf/ 
MacPrint,EditGlobals, 


{$S 


Init 


} 


Editlnit, 


{$S 


Print 


} 


EditPrint, 


{$S 


InOut 


} 


EditRead,EditWrite, 


{$S 


Format 


} 


EditForiaat; 



Segments are loaded automatically by calling a procedure or function within 
that segment. To unload a segment, you call the OS routine UnhadSeg, passing 
to it the address of any procedure or function within that segment. For example, 
if Editlnit contained the procedure Initialize^ then you would call 

anloadSeg(@Initialize) ; 

You need to call this from somewhere outside of the segment containing Ini- 
tialize. The main body of the application would probably be the safest place. 



VNITMOVER 



You don't have to use a {$U{filename)} directive when using the Pascal Run-time 
Support units or the Macintosh Interface units. That's because all those units 
have been moved into the actual Turbo Pascal compiler file. When you compile, 
those units are always ^visible'' and able to be used if you want. 

Suppose you have a well-designed and thoroughly debugged unit that you 
want to add to the standard units, so that you don t need a {$U} directive each 
time you want to use it. Is there any way to move it into the Turbo Pascal 
application file? Yes, by using the UNITMOVER utility. 

You can also use the UNITMOVER to remove units from the Turbo Pascal file, 
reducing its size and the amount of memory it takes up when loaded. 



Summary 



As you Ve seen, it's really quite simple to write your own units. A well-designed, 
well-implemented unit simplifies program development, since you just solve the 
problems once and not for each new program. Furthermore, once you Ve 
designed a useful unit, you can release it into the public domain without having 
to disclose your source code. Others can benefit from your expertise, but you 
won't have to divulge your methods. 
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CHAPTER 



Writing Your Own Macintosh Applications 



In previous chapters, you learned how to write a standard Pascal program. Now 
you can move into the meat of this manual: Macintosh programming. Well now 
show you parts of sample programs — contained in the EXAMPLES folder in the 
Utilities & Sample Programs disk — ^that illustrate general Macintosh program- 
ming techniques. 

You're not going to learn everything in this chapter. Inside Macintosh, the 
book on the Toolbox and the operating system, is over 1,200 pages. Macintosh 
Revealed, the two-volume work on how to program the Mac, is some 1,100 pages. 
Despite this chapter's comparative shortness, however, you should learn the 
basic skills necessary to program the Macintosh with Turbo Pascal. 



The Demo Program 



The EXAMPLES folder contains several sample programs. The following 
sections explain the parts of these programs that exemplify Macintosh program- 
ming techniques. One example program, MYDEMO.PAS, uses most of the 
techniques mentioned in this chapter. It is a fairly simple Macintosh application 
that uses menus, windows, dialog boxes, and graphics. Let's start by making it 
run, so that as you learn about it, you'll have in mind what the finished program 
looks like. 
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MYDEMO uses a resource file to define its menus, windows, and icon. The 
source text describing the resources is located in the file MYDEMO.R (also in 
the EXAMPLES folder). You can think of the text in MYDEMO.R as being like 
an uncompiled Pascal program: It needs to be run through a "compiler" to be 
useful. That ""compiler** is RMAKER (for Resource Maker), so first run 
RMAKER by double-clicking it (or use the Transfer menu, if you're in Turbo 
Pascal). (RMAKER is described in detail in Chapter 12.) 

Once you're in RMAKER, you'll get the standard file selector box; it only 
shows files ending with .R. Find MYDEMO.R, select it (point at it with the 
mouse, then cUck), and then click on the Open button. RMAKER then builds a 
resource file (MYDEMO. RSRC) based on the descriptions in MYDEMO.R. 
When it's done, exit by clicking on the Quit button near the lower left corner of 
the window. (You can also select the Other command in the Transfer menu, then 
choose Turbo when the file selector comes up.) 

Enter Turbo Pascal and open MYDEMO. PAS: Double-click directly on 
MYDEMO. PAS or double-click on the Turbo Pascal icon, close the Untitled 
window that's automatically opened, select the Open command from the File 
menu, find MYDEMO. PAS in the file selector list, and select it. Now, compile 
and run MYDEMO: Select the Run command from the Compile menu (or type 
{^I2J)- The compilation takes just a few seconds; MYDEMO runs, and the win- 
dow and the menu bar (with four menus) appears. 

Play around with MYDEMO for a while. Note that you can execute most 
commands with keyboard equivalents. You can resize the window, drag it around 
the screen, or close it (which will cause MYDEMO to halt execution and return 
you to Turbo Pascal). You can run desk accessories using the Apple menu, or 
bring up the About MYDEMO... dialog box. 

When you're done, exit MYDEMO: Either click the Close box in the upper 
left corner of the window, select the Quit command from the Edit menu, or type 
Igyo) . Once you're back in Turbo Pascal, select the To Disk command from the 
Compile menu (or type Q^)- Now exit Turbo Pascal. You should see the appli- 
cation icon for MYDEMO. You can double-click the icon to run the program 
again. 

Let's now look at how Mac applications are designed, by studying the parts 
that make up a Mac program. 
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Event-driven Programming 



Back in Chapter 6, the concept of event-driven programming was introduced. As 
you saw, the basic structure of most Macintosh apphcations is nearly identical, 
with a main body that looks something like this: 

begin { main body of program } 

Initialize; { set everything up > 

repeat { keep doing the following } 

SysteniTask; { update desk accessories } 

CursorAdjust; { update which cursor } 

if GetNextEvent(everyEvent,theEvent) then { if there's an event... > 
HandleEvent(theEvent) { ...then handle it } 

until Finished; { until user is done > 

Cleanup { clean everything up } 

end. { of program } 

The program sets up once with the user-defined routine Initialize. It then 
enters a loop that continues until some condition (such as the user selecting Quit 
in a menu) causes it to set the boolean flag Finished to true. 

Within that loop, it performs two major tasks. First, it calls SystemTask (a 
Toolbox routine), which allows the Mac operating system to update any desk 
accessories that might be in use. Second, it calls GetNextEvent (another Toolbox 
routine) to see if any events have occurred. If any have, the highest priority 
event is returned in the data structure theEvent, The program then passes the 
event to HandleEvent, which is a user-defined routine that handles all the difiFer- 
ent events that might occur. Such events include key presses, selection of menu 
items, mouse clicks, and windows being opened, closed, uncovered, or resized. 
When the program is ready to terminate, it calls the user-defined routine 
CleanUp. 

Event-driven programming assumes that most of your commands will usually 
be available, so you need to anticipate how to handle them. That won't be true 
all the time; for example, a program may have editing capabilities, but any edit- 
ing commands would be active and make sense only when there is a window 
open for text editing. It is difficult to select, cut, and paste text when there's no 
text to cut and no window open for the text to be pasted to. 

Event-driven programming takes some getting used to, but once you under- 
stand how it works and have seen examples of it, it is easy to apply to diflFerent 
situations. With Macintosh applications, the format is so standard that you can 
move from program to program and see almost identical code in the main bodies 
and immediate supporting routines. 
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A Note on Programming Style 



Turbo Pascal programs should be written to be as easy to read and modify as 
possible. In the example programs on the disk, almost every line of code is 
commented on. This may seem excessive, but the often cryptic nature of Macin- 
tosh system calls makes it helpful to understand exactly what each call is doing, 
and why. Too often, Macintosh sample programs assume too much understand- 
ing on the part of the reader. 

Emphasis has been placed on organizing programs into small, manageable 
chunks of code. Mac hackers sometimes enjoy stuffing all the event handling into 
a few gigantic case statements, usually embedded in loops and if/then/else state- 
ments, with so much indentation and nesting that the program is unreadable. 



Program Organization 



Although Macintosh applications tend to have the same structure, you might not 
notice it at first, given the way some of them are coded. Here is a skeleton 
structure for a sample Macintosh program: 

prograi SaniplePrograro; 

global declarations 

utility procedures and functions 

menu-driven procedures and functions 

event-handling procedures and functions 

initialization and cleanup procedures 

main body of program 

You Ve already seen what the main body of the program looks like; let's con- 
centrate on another aspect, event handling. 
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Event Handling 



To understand Macintosh applications, you must understand how to handle 
events. Following is a sample of the HandleEvent procedure in a typical pro- 
gram: 



procedure HandleEvent (theEvent 
begin 

case theEvent.What of 



EventRecord) ; 



DoHouseDovn(theEvent) ; 
DoKeyPress ( theE vent ) ; 
DoKeyPress(theEvent) ; 
DoUpdate(theE7ent) ; 
DoActivate ( theE vent ) 



{ mouse button pushed } 
{ key pressed down } 
{ key held down } 
{ window need updating > 
{ window made act/inact > 



nouseDown 
keyDown 
autoKey 
updateEvt 
activateEvt 
end 

end; i of proc HandleEvent > 

When an event occurs, the operating system creates an event record and 
sticks it in a queue, ready for you to handle. To see if there's one waiting, you call 
GetNextEvent, a boolean function that returns true if there's an event there for 
you. You give it a mask of the events you're interested in; you can use the 
predefined mask EveryEvent to look at all events. This event is passed to 
HandleEvent, which takes care of it. 

The key to all this is the predefined data type EventRecord, which is what 
GetNextEvent passes back to you (through the parameter list). The data structure 
looks like this: 

type 

EventRecord = 
record 

What : Integer; 

Message : Longint; 

When : Longint; 

Where : Point; 

Modifiers : Integer 

end; 

Here's what each of the fields mean: 



{ event code } 

{ event message } 

{ ticks since startup } 

{ mouse location } 

{ modifier flags } 



What tells you what type of event has just occurred. There are a total of 16 
predefined events, including 4 set aside for application use. Some common 
events include mouse down, key pressed, key repeated, window activate/ 
deactivate, window update, and disk inserted. 

Message contains information specific to the event that has occurred. For key- 
board events, it has both the ASCII and keyboard codes in it; for window 
events, it has a pointer to the window involved; for disk events, it has the 
drive number and File Manager result code. 
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• when is the time that the event occurred. This is given in the number of ticks 
(1 tick equals l/60th of a second) that have elapsed since you booted the Mac. 

• Where tells you the mouse^s location, in global coordinates, when the event 
happened. The data structure Point is a variant record whose components can 
be accessed either as V (Y coordinate) and H (X coordinate) or as VH[0] and 
VH[1], 

• Modifiers ofiFers yet more specific information, when appropriate. Each piece 
of information is flagged with a single bit, though not all bits are currently in 
use. Items include the status of the mouse button, Command key. Shift key, 
Option key, and Caps Lock key, and whether a window is being activated or 
deactivated. 

All this information gets passed to HandleEvent via the variable theEvent (of 
type EventRecord). HandleEvent is just a case statement using the What field in 
theEvent to determine which of the four procedures to call. 

There are additional events you could check for (such as mouseUp, keyUp, and 
so on), but these are suflScient for most programs. Here's a brief explanation of 
the types of events mentioned and what the handling routines will have to do: 

• mouseDown: The user has moved the mouse to some point and pushed the 
button. DoMouseD own determines where the mouse currently is (in a menu, 
in a window, and so forth) and takes appropriate action (the following section 
explains this further). 

• keyDown: The user has pressed a key. All this program does is check to see if a 
command-key combination was pressed; if so, it checks if the key is a menu 
command and takes appropriate action. 

• autoKey: The user is holding a key down. This program takes the same action 
as for keyDown. 

• updateEvt: A window has to be updated (redrawn) because of some event 
(resizing or removing a blocking window, for example). 

• activateEvt: A window has just been activated (brought to the fi-ont and high- 
lighted) or deactivated (another window was activated). 

As you can see, there can be a lot of background activity going on while your 
program is running. Fortunately, your program doesn't have to keep looking all 
over the place to figure out what to do because the operating system keeps it 
informed on what has happened, feeding it each event as the event occurs and is 
processed. Your program then decodes the event and uses a case statement to 
call the procedure best equipped to handle it. As you'll see, further decoding 
often takes place to pin down exactly what the event was. 
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Handling Mouse Events 



The greatest variety of events comes from clicking the mouse's button. The rou- 
tine DoMouseDown determines which window (if any) the mouse was in when 
the cUcking took place and where exactly it happened. Like HandleEvent, 
DoMouseDown is mostly a ease statement: 

procedure DoMouseDown (theEventrEventRecord) ; 
var 

Location : Integer; 
thetfindow : WindowPtr; 
MLoc : Point; tfLoc : Integer; 
begin 

MLoc := theE vent. Where; { get mouse position } 

HLoc := FindWindotf{MLoc,theHindow); { get window, window location } 

case tfLoc of { handle locations } 

InMenuBar : HandleMenu(MenuSelect(MLoc) ) ; { in the menu > 

InContent : HandleClick(theWindow,MLoc) ; { inside the window > 

InGoRway : HandleGoRway(theWindow,MLoc) ; i in the go away box } 
InGrow : HandleGrow{thetfindow/MLoc) ; { in the grow box } 

InDrag : DragWindow(thetfindow,MLoc,DragRrea) ; { in the drag bar > 
InSysffindow : SystemClick(theEvent,thetfindow) { in a Dft window > 

end 

end; { of proc DoMouseDown > 

DoMouseDown now has a number of sub-events to process, namely: 

• InMenuBar: The user has selected a command from one of the menus in the 
menu bar. Decode the command and take appropriate action. 

• InContent: The user has clicked the mouse down in the text or contents area of 
the window. If the window is the currently active one, take whatever action is 
appropriate (if any); otherwise, make it the active window. 

• InGoAway: The user has clicked the Close box in the window. If this is the 
active window, then you should close the window and possibly exit the pro- 
gram as well. If it's not the active window, make it the active window. 

• InGrow: The user has clicked the mouse in the grow box in the lower right 
corner of the window. Call some standard Toolbox routines (GrowWindow, 
Size Window, InvalRect) to let the user change the size and redraw the now- 
changed window. 

• InDrag: The user has clicked the mouse down in the drag bar at the top of the 
window. Call the Toolbox routine DragWindow, which handles everything for 
you. 
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• InSysWindow: The user has cHcked the mouse in a desk accessory window. 
Call the Toolbox routine SystemClick, which passes the event information on 
to the desk accessory (which then handles things itself). 

Two of these events (InDrag and InSysWindow) are handled by a simple call to 
a Toolbox routine. The other four {InMenuBar, InContent, InGoAway, and 
InGrow) result in calls to other procedures (HandleMenu, HandleClicky Handle- 
GoAxjoay, and HandleGrow, respectively). Let*s talk about each of these. 



Menu Commands 



The procedure HandleMenu decodes the mouse position and figures out which 
menu and which item in that menu were selected. It uses a case statement to 
select the action for the appropriate menu; the menu value is the ID assigned 
when the menu is created (more on this in the section on initialization near the 
end of this chapter). The commands in a menu are numbered from the top down, 
with the first command having a value of 1. The action itself is usually a second 
case statement, based on the menu item (or command) number. Here's a sample 
HandleMenu routine: 



procedure HandleMenu(MenuInfo 
var 

Menu : Integer; 

Item : Integer; 

B : Boolean; 

begin 

if Menulnfo <> D then 
begin 

ClearWindow(MainPtr) ; 

PenNormal; 

HideCursor; 

Menu HiWord(MenuInfo) ; 
Item := LoHord { Menulnfo) ; 
case Menu of 
ApplMenu 



if Item = 
DoAbout 



LongInt) ; 

{ menu number that was selected } 
{ item in menu that was selected > 
{ dummy flag for SystemEdit call > 



r we'reclearing the window } 
{ set the pen back to normal > 
{ turn off the cursor } 
find which menu the command is in } 
{ get the command number > 
{ and carry it out } 



1 then 



FileMenu 



EditMenu 



else DoDeslcAcc{Item) ; 
case Item of 
NewFile; 
OpenFile; 
SaveFile; 
Quit; 



{ bring up "About..." window > 
{ start desk accessory > 



1 
E 
3 

end; 
case Item of 
Undo; 
Cut; 
Copy; 
Paste; 
Clear; 

ShowClipBoard; 



1 
3 

5 
h 

end 



{ start a new file window } 
{ open an existing file > 
{ save file to disk > 
{ quit the program > 



{ undo last operation } 

{ cut to clipboard } 

{ copy to clipboard > 

{ paste from clipboard } 

{ clear clipboard } 

{ show clipboard window } 



{ other application menu case statments go here } 
end; { case of Menu > 
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HiliteMeiiu{D) ; { reset menu bar > 

if Menu = lOMenu then 

UpdateMenu; { make any changes needed > 

ShowCursor { turn the cursor back on > 

end 

end; { of proc HandleMenu > 

When an item in a menu is selected, the name of that menu (in the menu bar 
at the top of the screen) is highUghted, that is, inverted to white-on-black (called 
inverse or reverse video). When you are done processing the menu command, 
restore the menu bar to normal: call HiliteMenu(0), which is at the bottom of 
HandleMenu. Another procedure is called before you can leave HandleMenu: 
UpdateMenu, a local procedure that tests to see if certain items need to be 
enabled or disabled. 

Notice that in the EditMenu, item numbers 2 and 7 are not used. These are 
used by division lines and are not selectable as menu items. 

Enabling and Disabling Menu Items Just as the line separators in menus are 
disabled, you have the ability to disable (and enable) specific items in specific 
menus. For example, in the standard Apple edit menu, the paste item is not 
enabled until something is placed on the Clipboard. To enable and disable menu 
items, call the standard Macintosh procedures Enableltem and Disabhltem. 

Here's a sample UpdateMenu, with the SetltemState procedure it calls: 

procedure SetIteiiiState{Mndx,Indx : Integer; Flag : Boolean); 
begin 



{ test enable/disable flag > 
{ enable menu item } 
{ disable menu item > 



{ edit Cut is always active > 
{ edit Copy is always active > 
{ edit Paste depends on flag > 



if Flag then 

Enable: ten ( HenuList [ Hndx ] , Indx ) 
else Disableltem ( MennList [ Mndx ] , Indx) 
end; { of proc SetltemState > 

procedure UpdateMenu; 
begin 

SetIteinState(EditMenu,l,True) ; 
SetIteiiiState(EditMenu,E/True) ; 
SetltemState ( EditMenu , 3 , ClipBoardFull ) 
end; < of proc UpdateMenu } 

UpdateMenu calls the procedure SetltemState, passing the menu index, the 
item number, and a Boolean flag. SetltemState, in turn, decides whether to 
enable or disable the item based on the Boolean value passed to it. It uses the 
menu index passed to it to choose the particular menu handle from MenuList 
(an array of type MenuHandle), then uses that and the item number to call either 
Enableltem or Disableltem — Toolbox routines that do just what their names sug- 
gest. 

In the UpdateMenu procedure, the Edit menu command Paste is enabled or 
disabled depending on the Boolean flag ClipBoardFulL 
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check Marks You can have a menu item that uses a check mark and a global 
flag to keep track of a particular option. When this option is selected, a check 
mark is placed by the item in the menu; when it is de-selected, the check mark 
disappears. 

The following general-purpose routine called TogghFlag provides check mark 
operations: 

procedure ToggleFlag(var Flag : Boolean; Mndx,Indx : Integer); 
var 

Ch : Char; 

begin 

Flag := not Flag; { toggle flag (for you) > 

if Flag then { if flag is true... } 

Ch := Chr(CheckMark) { then check item in menu > 

else Ch :« Chr(NoMark); { else clear any checkmark > 

SetIteraMark(MenuListCMndx],Indx,Ch) { put char by item in menu } 
end; { of proc ToggleFlag > 

TogghFlag takes three parameters: a Boolean variable (Flag), the menu num- 
ber (Mndx), and the item number (Indx). ToggleFlag then toggles Flag; that is, if 
Flag was set to true, it is set to false, and vice versa. Having done that, it sees if 
Flag is now true or false: If Flag is true, it places a check mark at item Indx in 
menu Mndx; if Flag is false, it places a blank there, erasing any existing check 
marks. The standard Macintosh procedure SetltemMark puts the character next 
to the menu item. 

The *About...'* Box Most menu commands call other procedures that take 
the desired action. The first menu (ApplMenu) is the Apple menu; it appears at 
the far left of the menu bar as the Apple logo. When you pull down this menu, 
the first item you see is About <the program name>. If this is selected, the proce- 
dure DoAbout is called. Here's a sample procedure definition: 

procedure DoAbout; 
var 

theltem : Integer; 

ftboutPtr : DialogPtr; 
S1,SE,S3,S^ : Stress; 
begin 

SetCursor(CursList[!nyCursorl**) ; { set to my cursor > 

ShowCursor; { and turn it back on > 

51 := 'This is a Sample Program'; { set up four strings for the } 

SE :* ' brought to you by the '; { About dialog box } 

S3 := ' friendly folks at'; 
S^ :« ' BORLAND INTERNATIONAL'; 

ParaiiiText{Sl/S2,S3,S4) ; { set up as parameter text > 

AboutPtr := GetNewDialog(AboutID,NIL/Pointer(-l) ) ; { get a dialog box } 
lIodalDialog(NIL, theltem); { put dialog box up; get result > 

DisposDialog( AboutPtr) ; { get rid of dialog box > 

SetCursor( Arrow) 
end; { of proc DoAbout > 
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DoAbout is a small routine that displays a box with some information about 
the program, then waits for you to click on the OK button. Once that's done, it 
removes the box and lets the program continue executing. It uses a predefined 
dialog template in a resource file to create the display box. 

This dialog is known as modal dialog, because the entire program stops until 
you do something. The Toolbox routine ParamText provides a means of substitut- 
ing text strings in parameter items in subsequent dialog or alert boxes. The 
Toolbox routine GetNewDiahg uses the AbmtID to retrieve a predefined dialog 
box from a resource file. This allows you to have standard dialog boxes whose 
items have similar types, locations, and contents. The Toolbox routine Modal- 
Dialog sets up the dialog box for you; the routine DisposDialog then gets rid 
of it. 

Handling Desk Accessories The Apple menu also allows you to bring up 
desk accessories from within your program. The idea behind desk accessories is 
that you should be able to access them while you re in the middle of an applica- 
tion. Chapter 10 discusses desk accessories and how to write your own; for now, 
let s see how to make sure your program supports them. 

First, you must be sure to set up the Apple menu. This should be the first 
(leftmost) menu. To define the Apple logo as the title, use the character with hex 
value 14; in the resource file, you can do this by giving the logo the title \14. 

Here's what a resource file would look like: 

TYPE MENO 

,1DDD ; resource ID number 

\1< ; Apple symbol for title 

About My Demo... ; top item— for 'About' box 

(- ; line separator 

In the initialization procedure, after reading the menu data in (using Get- 
Menu), you need to add the desk accessories to the menu. You do this by calling 
AddResMenu(<menuhanclle>, 'DRVR'), where (menuhandle) is the handle of your 
first menu. 

Within your main loop, you need to call SystemTask to give the operating 
system a chance to pass control to any desk accessories that might be executing. 
If you get the mouse event inSysWindow, call SystemClick in order to let the 
desk accessory handle it; likewise, the mouse event inGoAway must call 
ChseDeskAcc if the window being closed is a desk accessory. 

If you select one of the desk accessories from the Apple menu, you need to 
start it up. The procedure DoDeskAcc — ^which HandleMenu calls for any item 
from the Apple menu other than the first one — does this by calling Getltem to 
get the name of the desk accessory selected, then calfing OpenDeskAcc with that 
name. 
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You should support the standard Edit commands — Undo, Cut, Copy, Paste, 
and Clear — ^since a number of desk accessories rely upon these. Set them up as 
items 1, 3, 4, 5, and 6, respectively, in a menu. When one is selected, pass its 
value (less one) to the OS function SystemEdit, which will return true if that edit 
command was for a desk accessory. If SystemEdit returns false, then handle the 
command in the manner appropriate for your application. 

Clicking Windows 

The following procedure handles clicking the mouse. The code checks to see if its 
own window is being clicked and if that window is the active window. If it isn't, 
then it makes its window active: 

procedure HandleClick(WPtr : WindowPtr; MLoc : Point); 



end; { of proc HandleClick > 

For other applications, though, more can (and needs to) be done. Some pro- 
grams have a picture, layout, or graph of some kind in the window. In that case, 
you need to look at exactly where the mouse was clicked and determine what 
action to take. For example, pointing at a section of the picture could bring up a 
dialog box telling the user what that section is and allowing the user to modify 
some data related to it. 

For a text-editing application, you click in the window in order to move the 
cursor to a different spot for text entry. In that case, you need to make the 
necessary calls to relocate the I-beam (text) cursor and to make sure that any text 
typed after that is inserted at the proper spot in the text record. 

The Close Box 

A window can have a Close (or go-away) box in its upper left corner. The user 
closes windows by pointing at the box with the mouse, then clicking once. On 
most text editors, including Turbo Pascal, the window closes, but the application 
continues to execute. In the following procedure, the flag Finished is set to true 
when that happens, leaving a procedure called CleanUp to actually close the 
window: 

procedure HandleGoAway(WPtr : WindowPtr; MLoc : Point); 



begin 

if HPtr « MainPtr then 
if WPtr <> Fronttfindow 
then Select»indotf(WPtr) 



{ if this is our window... > 
{ and it's not in front... > 
{ ...then make it active } 



var 



WPeek : WindowPeek; 

begin 



{ for looking at windows } 



if WPtr = FrontWindow then 
begin 



{ if it's the active window } 



WPeek := WindowPeek ( tfPtr ) ; 



if TrackGoAway(WPtr/MLoc) then 



{ peek at the window } 
{ and the box is clicked } 
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begin 

if WPeek^.WindowKind = userKlnd then { if it's our window > 
Finished := true { then time to stop } 

else CloseDeskAcc(WPeek''.tfindowKind) { else close DeskAcc } 
end 
end 

else SelectWindow(WPtr) { else make it active } 

end; { of proc HandleGoAway > 

As you can see, HandleGoAway doesn't act immediately upon the Close box 
being clicked. Instead, it calls the Toolbox function TrackGoAway, which returns 
a value of true or false. TrackGoAway allows the user to have a change of mind; 
by moving the mouse away from the Close box without releasing the mouse 
button, the user cancels the close request. 

This routine also handles closing desk accessories. It does this by checking 
what kind of window is open. During initialization, the main window was set to 
type userKind (=8), while the desk accessories use their reference numbers to 
identify their windows. Indeed, that's how the desk accessory is closed: by using 
the WindowKind Sield as the reference number to identify which desk accessory 
to close. 



The Grow Box 

A window also can have a Grow box in the lower right corner. The user can point 
the mouse here, hold the button down, and resize the window by dragging the 
mouse around. More accurately, resizing takes place when the program calls 
GrowWindoWy and what actually gets moved around is a dotted outline of the 
window. GrowWindow then returns the new width and height, with the position 
of the upper left corner being the fixed point of reference. The window is resized 
by calling SizeWindow with the new width and height. InvalRect is then called 
to mark any portions of the window that might no longer be valid because of the 
resizing. Here's a sample routine: 

procedure HandleGrow(WPtr : WindowPtr; I5Loc : Point); 
type 
GrowRec = 
record 
case Integer of 

D : (Result : Longint); 

1 : (Height, Width : Integer) 

end; 

var 

Growlnfo : GrowRec; 
begin 

if WPtr = MainPtr then { if it's our window > 

with Growlnfo do 
begin 
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Result :« Grovffinclow(WPtr,MLGC,GrowArea) ; { get amt of growth } 
Sizeffindow(HPtr, Width, Height, true) ; < resize window > 

InvalRect(ffPtr'*.portRect) { set up for update } 

end 

end; < of proc HandleGrow } 

This approach is a lazy one; the entire window is marked for updating. In your 
own applications, you can (and may want to) mark just those sections that have 
changed and need to be redrawn. In either case, the system issues update 
events (updateEvt) as needed to redraw things. 

You may notice that one of the parameters to GrowWindow is the rectangle 
GrowArea. This defines the bounds of growth, that is, the minimum and maxi- 
mum width and height for the window. GrowArea is initialized in the procedure 
Initialize, The minimum size is set there (rather arbitrarily) to 50 pixels wide by 
20 pixels high. The maximum size is based on the screen dimensions, which are 
not assumed but instead are copied from Screenbits. Bounds and adjusted 
inwards slightly. 

The Drag Bar 

A window can have a drag bar across the top. The user can point at the drag bar, 
hold the mouse down, and move the window around the screen. This is an easy 
event to handle; just call the Toolbox routine DragWindow. If any update events 
are required — ^for example, if the window were partially oflF the screen and you 
just dragged it all the way back on — ^the system issues the necessary update 
events. 

Note that DragWindow, like GrowWindow, gets passed a bounding rectangle 
called DragArea. It determines how far oflF the screen you can move the window. 
The idea, of course, is to avoid moving the window off the screen in such a 
manner as to prevent you from moving it back in. As with GrowWindow, Drag- 
Window is set using the values in Screenbits. Bounds. 

Handling Keyboard Events 



After this discussion of mouse events, keyboard events will seem relatively sim- 
ple and straightforward. There are three keyboard events: keyDown (a key is 
pressed); keyUp (a key is released); and autoKey (a key is held down long enough 
for it to start automatically repeating). The second one is only of interest in 
special cases, and you can often handle the third the same as the first. So you 
only have to worry about one event at this point: A key (or combination of keys) 
has been pressed. 
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For a regular application, a key press signals one of three things/First, if text 
entry is active, it means that a text record is being modified, that is, you're typing 
text in. Second, your program may interpret certain key combinations as special 
commands. Third, the key press may be the command-key ((^) equivalent of a 
menu selection. 

If you pull down most Macintosh application menus (except for the Apple 
menu), youll see the command-key equivalents beside the items. To invoke a 
given command, hold the command ([^) key down and press the appropriate 
letter. Here's the routine to handle it: 

procedure DoKeypress(theEvent : EventRecord); 
?ar 

KeyCh : Char; 

begin 

if (theEvent. modifiers and cmdKey) <> 0 then 
begin 

KeyCh ;- Chr{ theEvent. Message and charCodeHask) ; 
HandleHenu ( HenuKey ( KeyCh ) ) 
end 

else Sys6eep(l) 
end; { of proc DoKeypress > 

The Modifiers field in theEvent includes a bit that is set to 1 if the command 
key was held down when the event happened. You can test for that bit with a 
predefined mask, cmdKey, If you pass the character to the Toolbox function 
MenuKey, it will return a Longint value containing the menu and item numbers. 
Pass these numbers to your menu-handling routine, which will split them up 
into two integers to separate the menu and item numbers. 

Handling Update Events 



The Macintosh keeps track of a lot of things for you. For one, it tells you when 
some portion of a window needs to be redrawn^ because of resizing or removing a 
covering window. This is known as an update event (updateEvt), and it requires 
special handling. For one thing, you need to be able to redraw your entire win- 
dow (or some portion thereof) at any time. This isn't that difficult for a text- 
editing window, since the text is stored oflF in memory and is written to the 
window as needed. However, it's a little trickier for a window with graphics. You 
either have a procedure (or set of procedures) that can recreate what you have on 
the screen, or you need to write to a bitmap that's in memory and copy it to the 
window as needed. 



{ menu key command > 

{ decode character > 

{ get nenu and iten > 

{ do something } 
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To handle an update event, follow a given sequence. Here's an example: 

procednre DoUpdate(the£vent : EventRecord) ; 
var 

SavePortrtheWindow : WindowPtr; 
begin 

theWindow :» WindowPtr(theEvent.Message) 
if theWindow « MainPtr then 
begin 

SetCursor(CursList[watchCursor3''*) ; 

6etPort(SavePort) ; 

SetPort ( theWindow ) ; 

BeginUpdate(thetfindow) ; 
{ and here's the update stuff! > 

ClearWindo¥( theWindow) ; 
{ now^ back to our program...} 

EndUpdate( theWindow) ; 

SetPort ( SavePort ) ; 

SetCiirsor( Arrow) 
end 

end; { of proc DoUpdate } 

This saves the current grafport into SavePort and makes theWindow the cur- 
rent port so that you can write to it. BeginUpdate limits all output to the section 
of theWindow that needs updating. You then do whatever redrawing is needed. 
When you're done, EndUpdateliA^s those limits, and SetPort{SavePort) restores 
the old grafport. 



; { find which window > 

{ only update ours > 

{ set cursor to watch > 

{ save current grafport } 

{ set as current port } 

{ signal start of update > 

{ do update stuff } 

{ signal end of update } 

{ restore grafport > 

{ restore cursor > 



Handling Activate Events 



On the Macintosh desktop, only one window can be active at any one time. This 
doesn't mean that changes can't occur in other, inactive windows; it just means 
that, if there is more than one window on the screen, the highlighted front 
window is considered the active window. The Macintosh interface states that 
clicking on a window makes it active (and all others inactive); other processes 
(including a direct call to SelectWindow) can also make a window active. Here's 
an example: 

procedure DoActiyate(theEvent : EventRecord) ; 
var 

I : Integer; 

AFlag : Boolean; 
theWindow : WindowPtr; 
begin 

with theEvent do 
begin 

theWindow := WindowPtr( Message ) ; { get the window > 

AFlag := Odd(Modif iers) ; { get activate/deactivate } 

if AFlag then 

begin { if it's activated... } 

SetPort ( theWindow ) ; { make it the port } 

FrontWindow theWindow; -C know it's in front > 
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DrawGrowIcon(theWindow) ; 



{ set size box > 



end 



else 



begin 

SetPort(ScreenPort) ; 

if theWindow = FrontWindow 



{ else reassign port } 
{ if it's in front > 
{ . . .then forget that > 



then FrontWindow := NIL 



end; 



if theWindow = MainPtr then 



begin 

SetIteinState(EM,l,not AFlag); 
for I := 3 to b do 



{ if it's our window } 
{ update edit ciads } 



SetIteinState(EM,I,not AFlag); 
SetIteinState(EM,fl,aFlag) ; 
for I := PM to IM do 



{ update Quit command > 
{ update other menus > 



SetltemState ( I , D , AFlag ) ; 
DrawMenuBar 



{ update menu bar > 



end 



end 



end; { of proc DoActivate > 

You test for activate/deactivate using the lowest bit on the Modifiers field of 
theEvent. If the window is being activated, you need to call SetPort to make it 
the current grafport; if it's being deactivated, you need to do something else, 
depending on your application. SetPort is called with the variable ScreenPort, 
which earlier (in Initialize) had been set to the entire screen with a call to 
GetWMgrPort. Whether the window is being activated or deactivated, a call is 
made to DrawGrowIcon. 

Handling Other Events 



There are a few other events that can occur. The disk inserted event (diskEvt) 
can usually be ignored; the only time it*s important is during file selection, and, 
in that case, the Standard File Package reacts automatically. The network event 
(netivorkEvt) has to do with getting a packet via AppleTalk; see the appropriate 
documentation in Inside AppleTalk, as well as Chapter 10 in Volume 2 of Inside 
Macintosh, for more details. Likewise, the nature of a driver event (driverEvt) is 
dependent upon the device driver issuing it. 

The last four events are application-defined events; applEvt, app2Evt, 
appSEvt, and app4Evt. Since they're application defined, how do they get into 
the event queue in the first place? Simple: you put them there with the OS 
function PostEvent, PostEvent takes two parameters: the event code (which 
should be applEvt..app4Evt), and the event message, a Longint value that can 
be almost anything you want it to be (including a pointer to some data structure). 
The event code gets assigned to What, and the event message to Message; 
the other fields (Where, When, Modifiers) are all set for you by PostEvent. 
PostEvent then returns a result code (0=Ok, 1= Event code not allowed) telling 
you how it did. 
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Data Structures 



Until now, we Ve shown many program parts without talking too much about the 
data structures involved, other than the type EventRecord. 

First, you need to understand that Mac software is heavily based on the ideas 
of pointers and handles. If youVe programmed in Pascal or C before, you are 
probably familiar with the concept of a pointer: It's a variable that contains, 
instead of data, the address of where some data is stored. A handle is just a 
pointer to a pointer. Handles are used heavily in Mac programs, because they 
allow the Mac to perform memory reorganization — amoving data structures fix)m 
one place in memory to another — ^without changing any values. 

Here's the way it works: A handle points to a pointer, which in turn points to a 
data structure somewhere in memory. If the Mac needs to move that data struc- 
ture, the Mac relocates it and then changes the value of the pointer. The handle's 
value never changes — ^it's still pointing to the same pointer — and so the move- 
ment is invisible to the program. 

Handles carry the analogy of pointers directly: To access the data structure a 
pointer points to, you say P^, that is, the pointer variable's name followed by a 
caret. For a handle, refers to the pointer that the handle points to, and H^^ 
refers to the data structure. 

Menus are managed using handles. All the menu procedures and fiinctions 
work with menu handles, such as GetMenu, SetltemMark, Enabhltem, and 
DisabJeltem, Since almost all menu manipulation is done via predefined rou- 
tines, you should never have to directly access any field of the menu records. 

Windows are managed in a two-fold way, with both a WindowPtr {MainPtr) 
and a WindowRecord (MainRec). MainRec is used in the initial call to GetNew- 
Window, but is never really directly accessed. MainPtr, on the other hand, is 
used in almost all the window-based calls. MainPtr actually points to a structure 
of type WindowRecord, but you can't access it through MainPtr, since its 
declared data type is GrafPtr. Instead, you need to do the assignment MainPeek 
: = WindowPeek( MainPtr ) ; , where MainPeek is defined to be of type WindowPeek 
(which is equivalent to ^WindowRecord), You can then access the Window- 
Record fields via MainPeek^, 

QuickDraw, the graphics package, has some of its own data structures, most 
notably the types Point and Rect. Point is a variant record that allows you to refer 
to its X and Y components either as separate fields (V, H) or as elements of an 
array (VH[0] and VH[ 1 ]). The type Rect builds upon that: You can access its four 
coordinates as either separate fields (Top, Left:, Bottom, Right) or as two points 
(TopLeft, BottomRight), which in turn give you the options {V, H) or {VH[0]y 
VH[1]). 
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There are many other predefined data types, as well as numerous predefined 
constants. Most can be found by looking at the Macintosh Interface units in 
Appendix D and at Inside Macintoshy especially Volume 1. 



Resource Files 



There are two ways of defining windows, menus, and other data constructs spe- 
cific to your program. First, you can use calls to NewWindow, NewMenu, and so 
on, hardcoding the menu layout or window specs into the initialization section of 
your program. Or, you can lay it all out in a resource file, compile it using 
RMAKER, and link it into your program. Your initialization section can then 
load in the menu, window, and other information from the resource section of 
the application. 

A resource file contains items of diflerent resource types: STR (string), ICON 
(icon), MENU (menu), WIND (window), DLOG (dialog box), and so on. Each 
item is associated with a resource ID, such as 1000, 1001, and so on. These IDs 
need to be unique within a type; you can't have, say, two menus with IDs of 
1000. But you can have the same numbers as IDs for diflFerent types. For exam- 
ple, in the following resource file example, there are several items with 
ID =1000, but all are of difiFerent resource types: 

EXAMPLE 



TYPE MENU 
,1D0D 

\IA 

About Hy Demo. 
(- 



menus 

resource ID 

menu title (= Apple logo) 
first item 

second item: line separator 



,1DD1 
File 
New 
Open 
Save 
Quit 



resource ID 
menu title 
first item 



,lDDd 
Edit 
Undo/Z 
(- 

Cut/X 

Copy/C 

Paste/V 

Clear 

(- 

Show Clipboard 



resource ID (another menu) 
menu title 

first item (with character command equiv) 
line separators 
and so on. . . 



more menus go here 
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TYPE WIND 

,1D00 
My Demo Program 



window 
resource ID 
window title 

coordinates: yl/x5, y5/XE 
window attributes 
window type = documentProc 
refCon: user-definable info 



7 335 505 
Visible GoAway 
0 
D 



TYPE DLOG 



dialog box 
resource ID 
box title 
coordinates 
attributes 

window type = rDocProc 
refCon 

ID for dialog item list 



,1000 
About My Demo 
SO 50 IflO <tD 
Visible NoGoAway 
It 
0 

1000 



and so on. 



These IDs are used when you want to read the resource items from within 
your program. 

How do you associate a given resource file with a program? Two steps are 
necessary. First, the very first hne in a resource file names the file that the 
compiled resources should be written out to; by convention, that file has the 
extension .RSRC. Second, having run RMAKER on your resource file, you need 
to pull the resulting data file into your program when it compiles. You do that 
using the {$R (file)} compiler directive (not to be confused with the {$RH-/-} 
range-checking directive). For example, 

{$R Example. Rsrc> 

tells Turbo Pascal to copy in the resources from EXAMPLE. RSRC whenever it 
compiles a program. If you compile to disk, then the resource information is 
placed in the resource jork of the resulting application. That way, you can move 
and copy the application as much as you'd like, and the resources automatically 
go with it. 

There are two other compiler directives that tie into using resources. The first 
is the {$B+} directive, which sets the bundle bit. Briefly, the bundle bit tells the 
Mac desktop that the resources in your application should be installed and used 
as a group. This applies primarily to icons and file types. Using it allows you to 
define your own icon in your resource file, as well as icons for files produced by 
your application. 

The second directive is the {$T (filetype)}, which is used to define the file type 
smdfile creator for your program. The file type should (usually) be APPL, since 
you are producing an application. The file creator has two uses. First, it associ- 
ates the application with an icon; second, it allows a document to invoke your 
application when it's double-clicked, if the document is associated with the cre- 
ator type of your program. Again, this all ties in to the bundle concept. 
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Chapter 12 tells you how to use RMAKER and the format needed for your 
resource file. Additional information about resources can be found in Inside Mac- 
intosh, Volume I, Chapter 5, and Volume III, Chapter 1. 



Initialization 



Like the overall program, the initialization procedure for most Macintosh pro- 
grams follows a certain structure: 

• Call /mf routines. 

• Set up menus. 

• Set up windows. 

• Do other graphics initialization. 

• Do program-specific initialization. 

• Handle clicked documents. 

There is an Znif routine for most of the major managers. The first, and most 
important, is InitGraf(@thePort), That sets up QuickDraw (which is used by 
just about everything else) and sets up a grafport for the screen. Other Init 
routines you'll probably want to call are 

InitGraf (®thePort) ; < create a grafport for the screen } 

InitFonts; { start up the font manager } 

InitWindows; { start up the window manager } 

InitMenus; { start up the menu manager } 

TEInit; { start up the text manager for DRs > 

InitDialogs(NIL) ; { start up the dialog manager } 

FlushEvents(everyEvent,0) ; { clear events from previous state } 

Setting up menus involves four steps. First, you want to define the menus 
themselves. If you're using a resource file, just do a call to GetMenu for each 
menu handle, or even a single call to GetNewMBar. Otherwise, you have to 
build each menu using an initial call to NewMenu, followed by a call or calls to 
AppendMenu. Second, if you're handling desk accessories, call AddResMenu, as 
described earlier in this chapter. Third, add all the menus to the menu bar by 
making successive calls to InsertMenu, Finally, call DrawMenuBar to display 
the menu titles and make them active, as in 

MenuListLl] := GetMenu( ApplMenu) ; { read menus in from resource } 
MenuListCE] := GetMenu(FileMenu) ; 
MenuList[3] := GetMenu(EditMenu) ; 
{ get other menus in like fashion > 

AddResMenu(MenuList[l], 'DRVR') ; { pull in all desk acccessories } 
for Indx 1 to MenuCnt do { place menus in menu bar > 

InsertMenu(MenuList[Indx] /D) ; 
DrawMenuBar; { draw updated menu bar to screen > 



Writing Your Own Macintosh Applications 



99 



In addition to all that, you may want to make calls to Disableltem to disable 
any commands that shouldn't be active when your program starts, such as edit- 
ing commands (when no editing windows are open). 

As with menus, your window initialization takes several steps. If you need a 
window at startup, create it using either GetNewWindow {reading in from 
resources) or NewWindow (building it in place). In either case, you'll now have a 
pointer to your window, which is what you'll use for most window manager calls. 
Having created the window, make it the current grafport by calling SetPort, 
then make it the active window by cdlling SelectWindow, If it has a drag bar, 
define dragging limits (DragArea). Likewise, if it has a Grow box, define mini- 
mum and maximum size (GrowArea); you should also coSl DrawGrowIcon. For 
example: 

{ set up window stuff. } 

GetffflgrPort(ScreenPort); { get grafport for all windows } 

SetPort(ScreenPort); { and keep on hand Just in case > 

HainPtr := GetNewHindow{l!ainID,^MainRec,Pointer(-l) ) ; { get window } 

SetPort(MainPtr); { set window to current grafport } 

SelectHlndow(MainPtr); { and make window active } 

Fronttfindow HainPtr; { remeniber that it's in front > 

DrawGrowIcon{MainPtr); { draw the Grow box in the corner } 

MainPeek WindowPeek ( HainPtr ) ; { get pointer to window record } 

MainPeek*.windowKind :» UserKind; { set window type. * user kind (ID=a) } 

Screen Area := screenBits. Bounds; { get size of screen (don't assume) >. 

with ScreenArea do 
begin 

SetRect(DragArea/5,E5,Right-5,Bottoi-lD) ; { set drag region } 

SetRect (GrowArea, 5Q,EQ,Right-5, Bottom-ID) { set grow region > 

end; 

There is a fair amount of graphics initialization you can, but don't have to, do. 
This includes setting pen size, pattern, and mode; loading the cursor, either from 
the system or from your resource file; loading or defining patterns; loading icons 
and bitmaps; and similar tasks. 

Your program-specific initialization should probably come here. You've set up 
all you need to in order to do some work; if your program requires it, you're able 
to modify menus, windows, and other data structures and display elements. 

The last part of initialization happens only if you have an application that can 
be launched by opening a document associated with your application's creator 
type. For example, you can get into Turbo Pascal by double-clicking any program 
file created under it. You can detect this by making the following call: 

CountAppFiles(Msg,FCount) ; 

This returns two values: FCounty which tells you how many files were 
selected; and Msg, which tells you if the files were selected for printing or for 
opening. You can then set up a loop (Indx := 1 to FCount) and cslW GetApp- 
Files(Indx,AFRec), which will return information on each file to you, one at a 
time. Once you've handled that file, you can remove it from the list by caUing 
ClrAppFiles(Indx). 
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As is true with most aspects of Macintosh programming, the best way to learn 
is to see what others have done. You'll find a diverse variety of approaches in the 
sample programs on your Turbo Pascal disk(s); there's something to be gleaned 
fix)m each one. 

Cleaning Up 



Cleaning up on the Macintosh is actually minor; most details are automatically 
taken care of when you exit your program. There is a specific procedure, 
ExitToShell, which you can (but don't have to) call. It's useful if you have to abort 
in the middle of a program, although the Turbo Pascal routine Halt performs the 
same function. 



Large Programs and Segmentation 



The Mac limits the code size of a program to 32,768 bytes. When you need to 
write programs that exceed this limit, you must segment your program. This 
means dividing it up into chunks of less than 32K bytes each. 

Turbo Pascal makes segmentation simple. At the.start of your program, tell the 
compiler to produce a segmented code file by including the {$S+} compiler 
directive. 

This switch is oflF by default; you must explicitly turn it on to use segments. 
When segmentation is off, all subprogram (procedure and function) calls and 
subprogram address references are coded by the compiler using program coun- 
ter-relative instructions. When segmentation is on and you're using the {$S+} 
directive, all calls and address references are routed through the segment loader 
jump table. 

To segment your program, organize your procedures and functions— including 
those in a unit — ^into different segments. When you want to specify which seg- 
ment a procedure, function, or group of procedures and functions should be in, 
precede the specific item with the directive {$S segname}, where segname is a 
string of up to eight characters. 

NOTE: The $S directive is case-sensitive. {$S MySeg} and {$S mySeg} refer 
to two different segments. 

If segname is less than eight characters long, it will be padded on the right 
with blanks. All procedures and functions following it will be included in that 
segment until the next {$S segname} directive is encountered. 
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The default segment, or blank segment, is one whose name consists of eight 
blanks. This is where any procedures and functions declared before the first 
{$S «^gnam^} directive are stored. 

You can repeat segment names within a program, collecting procedures and 
functions in different parts of the program into the s^e segment. You can also 
organize your units into segments, as you saw in the last section of Chapter 8. 

When you compile a segmented program, the compiler stores the code seg- 
ments as resources in the code file. They have resource IDs starting at 1, which 
the compiler generates and uses to replace the segment names you assigned. 
Segments are mostly invisible to the program. To load in a segment, call any 
procedure or function located in that segment. If the segment isn't already in 
memory, it is loaded in. 

To remove a segment from memory, call the OS routine UnloadSeg, passing to 
it the address of any procedure or function in that segment. Suppose you had 
placed your Initialize and Cleanup routines in their own segment. The main 
body of your program might look Uke this: 

begin 

Initialize; { do initialization code } 

UnloadSeg(«Initialize); { unload the segment } 

repeat 

SystemTask; { let desk accessories work > 

if GetNextE7ent(everyE7ent/theEvent) i see if there is an event } 

then HandleEvent(theEvent) i if so, handle the event } 

until Finished; 

Cleanup 

end. { of prog MySegProg > 

After calling Initialize, call UnloadSeg and pass to it the address of Initialize. 
This frees the memory that Initialize's segment occupies, allowing the Mac to 
reclaim it if needed. When you call Cleanup at the end of your program, that 
segment is reloaded from the disk, if necessary. If that segment's memory wasn't 
used, then it has remained in memory and is called without any disk access. 



Summary Exercises 



Again, within the scope of this manual, much less this chapter, it is impossible to 
teach you all you need to know about programming on the Macintosh. But this 
manual gives you a good start, combined with the sample programs on the distri- 
bution disk. 

Try making changes to the program MYDEMO.PAS. Before doing so, make 
sure you are not working from your master (original) Turbo Pascal disk, but that 
you're using a backup copy. Each time you successfully modify something, be 
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sure to make a backup copy of that version. That way, if you later accidentally 
muck things up beyond recovery, you can always go back and start over again. 
Some exercises follow that review what youVe learned so far. 

Editing Resources 



Edit the STR resources in MYDEMO.R, inserting your name and the name 
of your firm in the appropriate places. Run RMAKER on it, recompile 
MYDEMO.PAS, select the About My Demo command in the Apple menu, and 
watch your name come up in the middle of the screen. 

NOTE: If you start to change file names, make sure the changes are made in 
all the right spots. MYDEMO.R's output file name (MYDEMO.RSRC) is 
located at the beginning of the file. If you change that name, you must make 
exactly the same change to the name in the {$R MyDemo,RSRC} directive at the 
start of MYDEMO.PAS. 

Adding Menu Items 



Add a new item to one of the menus. This consists of the following steps: 

1. Think up a relatively short name for it, say, Yahoo. 

2. Go into MYDEMO.R and add that name to the end of one of the menu 
lists. You can add a command-key equivalent for it, but it can't dupH- 
cate any of the other command keys. For example, use Yahoo/Y. 

3. Run RMAKER on MYDEMO.R. 

4. Go into MYDEMO.PAS. Go to the procedure HandhMenu, Find the 
case statement handle for the menu you modified. Add a new state- 
ment for the menu handler n : Do Yahoo (where n is the next available 
number for the menu). 

5. Add the new procedure, DoYahoo. It should have roughly the following 
structure: 

procedare DoTahoo; 
{ declarations > 
begin 

{ any setup for the procedure } 
{ procedure body } 
end; { of proc DoYahoo > 
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6. Save MYDEMO.PAS to disk. Select the Run command from the Com- 
pile menu. Fix any bugs you discover. Once it compiles and runs, go to 
the menu you modified and select the Yahoo command. Watch it run. 

Adding a New Menu 



Add a new menu to the program. Call the menu (and its commands) whatever 
you'd like; for now, we'll call the menu Stooges, with the commands Larry, 
Curly, and Moe. 

1. Go to MYDEMO.R. At the end of the menus, before the line TYPE 
WIND, type in the menu description as follows: 

stooges 
Larry 
Curly 
Hoe 

Save MYDEMO.R and run RMAKER on it. 

2. Get into MYDEMO. PAS. Go to the const section at the top of the file. 
Change MenuCnt irom 5 to 6. Right under the statement 

lONenu « 10D4; 

add the line 

StgsMenu = 1DD5; 

Right under the statement 

IM = 5; 

add 

SM = t; 

3. Go to the procedure Initialize. Right under the statement 
MenuListCIM] := GetMenu(IOMenu) ; 

add 

HenuListCSH] GetHenu ( StgsMenu ) ; 

4. Go to the procedure HandleMenu. Add a semicolon to the end at the 
end of the case statement for lOMenu. Add the following underneath 
it: 

StgsMenu : case Item of 
1 : DoLarry; 
e : DoCurly; 
3 : DoMoe 

end 
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5. Go to the end of the procedure DoFileDeJete. Right after its final end 
statement, add the following: 

procedure DoLarry; 
begin 

end; { of proc DoLarry > 

procedure DoCurly; 
begin 

end; { of proc DoCurly } 

procedure DoMoe; 
begin 

end; i of proc DoMoe } 

6. Save MYDEMO.PAS. Compile it until all the syntax errors are gone 
and it runs OK. Try out the new menu. 

7. Be creative: Put something in each of the procedures DoLarry, 
DoCurly, and DoMoe, 

Practice with these exercises until you feel comfortable enough to move on to 
the next chapter. In it, youll learn how to write a desk accessory. 
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CHAPTER 



Graduation: Writing a Desk Accessory 



Desk accessories are analogous to final exams in Mac programming: Once you Ve 
written a desk accessory, youVe graduated. Of course, there are still device 
drivers to wrestle with, but you can consider them graduate studies. In the 
meantime, get your cap and gown ready, because by the time you're done with 
this chapter, you'll be writing your own desk accessories. 

There are a couple of sample desk accessory programs on the Turbo Pascal 
disk. This chapter discusses writing desk accessories in general. After you're 
done reading, you can go and look at the samples to see working programs. 



Basic Theory and Structure 



Let's start oflF by looking at the overall format of a desk accessory, much as we 
looked at the overall format of a Mac application back in Chapter 9. Here's how 
your source file might be laid out: 

prograi ThisDeskAcc; 
{$D PasDeskacc} 
{$0-} 

uses <whatever units>; 

procedure Open(var Device: dCtlEntry); forward; 

procedure Control(var Device: dCtlEntry; Param: Longint; Code: Integer); 
forward; 
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procedure Close (var Device: dCtlEntry); 
forvard 

{ Global constants and data types > 
-C Support procedures and functions > 
{ Body of Open, Controls and Close procedures > 

begin end. 

The Open, Control, and Close procedures must be the first three procedures 
declared in the desk accessory program. They may have other names, but they 
must be declared in the above order and with the above parameter lists. 

• Open This procedure is called when the desk accessory is launched. It should 
do all the initialization: windows, menus, and so on. 

• Control This procedure is called each time the system wants the desk acces- 
sory to do something: respond to an event or handle a timer update, for ex- 
ample. 

• Close This procedure is called when the desk accessory is shut down. It closes 
up and disposes of the various items: windows, menus, and so on. 

One easy solution to ensuring that these routines are the first three is to 
declare them all forward at the start of your program, then have their bodies 
located later on. That allows them to call one another, and also allows them to 
share other procedures and ftinctions located between their declarations and 
their implementations. 

As you can see, the desk accessory structure is not unlike that of a standard 
Mac application, with procedures for initialization, event-handling, and cleanup. 
Unlike an application, though, a desk accessory has no main body; instead, the 
operating system makes all the appropriate calls to these routines. More accu- 
rately, the current application — ^be it the FINDER or some other program — 
makes the appropriate calls. 

Remember the discussion on supporting desk accessories back in Chapter 9? 
When a desk accessory (DA) is selected from the Apple menu, the application 
currently running launches it by calling OpenDeskAcc, which instructs the oper- 
ating system (OS) to load that DA into memory and then call its Open procedure. 
When the application calls SystemTask — ^as it should in its main loop and, for that 
matter, any other persistent loop — ^the operating system can then check to see if 
it needs to call the DA's Control procedure. Finally, when the application calls 
C loseDeskAcc, the OS issues the call to the DA's Close procedure, then purges it 
from memory. Likewise, when the application itself is finished, the OS issues 
calls to the Close procedure on any DAs still running (though it is possible to 
write a DA that continues to run after you exit an application). 
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Like an application, a desk accessory needs to handle most of the usual 
events — mouse down, key down, auto key, activate, update — ^and may have to 
provide support for windows, dialogs, and menus. As you might suspect, how- 
ever, there are significant differences in event handling between desk accessories 
and applications. There are three major differences. First, many events do not 
have to be handled by the desk accessory at all, since the application takes care of 
them. For example, the mouse-down event in a DA usually just has to do with an 
in-content event. Other events, such as the drsg bar and Close box,, are handled 
by the application. 

Second, other events are predigested by the operating system. Instead of han- 
dling the in-menu-bar version of the mouseDown event, the DA receives a code 
from the OS telling it that a menu item has been selected, along with the menu 
and item values. 

This is taken one step further with editing commands: When an application 
calls SystemEdit, passing to it a value in the set [1,3,4,5,6] (which correspond to 
the commands Undo, Cut, Copy, Paste, and Clear, respectively), the operating 
system calls the Control procedure with that specific information, so that the DA 
already knows which command has been selected. 

Third, a desk accessory has to respond to certain events that an application 
doesn't. For example, a DA can tell the operating system that it needs to be 
called periodically, such as once per second. The OS then issues those periodic 
calls — ^in addition to whatever other events might occur— telling the DA this is 
its periodic timed event, and the DA should do whatever it needs to. For exam- 
ple, it may have been told to update a clock. 

A desk accessory differs from an application in other ways as well. Perhaps the 
most significant is in the area of global variables: A DA doesn't have any. You can 
declare global constants, global data types, and global procedures and functions 
(in addition to Open, Control, and Close), but not global variables. This could be 
quite a hindrance, if there were no way around it. But, as you might guess, there 
is a workaround. The operating system passes the same data structure — a record 
of type dCtlEntry — to all three routines. One of the fields in that record, 
dCtlStorage, can be used as a handle (a double pointer, remember?) to a chunk 
of memory that holds whatever "global** data you need to be passed from Open to 
Control to Close, or that you need to be preserved between calls to Control. 

The fact that a desk accessory cannot have global variables also means that a 
DA may not use any units that depend upon global variables. In particular, this 
means that the PasInOut, PasConsoh, and PasPrinter units cannot be used by a 
DA, since these units declare and use global variables (such as the Input and 
Output files). The QuickDraw unit also declares global variables {thePort and 
arrow, for example), but as an exception to the rule, you may use QuickDraw as 
long as you don't refer to any of those variables in your DA. 
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Other differences and limitations exist. A desk accessory has to fit into a single 
segment, which restricts it to 32K. {Inside Macintosh suggests an 8K Umit, but 
this is due to historical reasons^ namely the limited memory on the earliest 
Macs.) In addition, a DA shouldn't have more than one menu and one window 
for itself, although again exceptions are possible. 

A comment on desk accessory design: A desk accessory is, by nature, mode- 
less. It runs concurrently with whatever application happens to be going on at 
the time, and you can usually switch back and forth between them. By the usual 
event handling, a DA can tell when it has been activated or deactivated, that is, 
when its window has been made the active one. Your design needs to accommo- 
date this and to make sure (as far as is possible) that your DA doesn't seriously 
interfere with whatever application might be running at the time. 



Data Structures 



Before we dive into a more detailed discussion on how to write Open, Control, 
Close, and any supporting procedures, we need to talk about the data structures 
that you can (and have to) work with. Three in particular are critical: the driver 
header, the device control entry (dCtlEntry), and your global data record (what- 
ever you name it). Let's discuss them in that order. 

Driver Header 



Device drivers — ^which include desk accessories^ — ^have a fixed format for the first 
20 bytes of their machine code. This section, documented in Inside Macintosh 
(Vol. II, Chapter 6, ''The Device Manager"), contains information about the 
driver itself, as well as offset pointers to the Open, Control, and Close proce- 
dures. Furthermore, device drivers (including desk accessories) must be of a 
particular file and creator type in order to be installed into your SYSTEM file as 
a resource. In short, if you want to produce a desk accessory, you have to ensure 
that the code file is properly set up. 

Turbo Pascal makes this easy to accomplish. Put the directive 
{$D PasDeskacc} 

right after your program header. This tells Turbo Pascal to do all the massaging 
and changing necessary to turn your program into a desk accessory code file. It 
defines your output file type as DFIL, which makes the output file appear as a 
suitcase (the icon used for fonts and desk accessories). The output file creator is 
set to DMOV, which allows you to double-click on the file icon in order to run 
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FONT/ DA MOVER. If necessary or desired, you can override these values using 
the {$T ttttcccc} compiler option, where tttt is the output file type and cccc is the 
output file creator. 

The code resource type is DRVR, which identifies the code as a driver. The 
resource ID is set to 12, which is the lowest possible value for a desk accessory. 
Since FONT/DA MOVER modifies the resource ID if needed in order to install 
the desk accessory into the SYSTEM file, you don't need to worry about whether 
other desk accessories already have this resource ID. However, if you are going 
to use a resource file for your desk accessory, you do need to know that those 
resources must have ID values in the range (—16000.. -15969); more about this 
later on. 

As mentioned, the PasDeskAcc driver header initializes the driver information 
fields. Four of these are copied into the corresponding fields in the device control 
entry (dCtlEntry) record (see next section) when the desk accessory is opened. 
Here are the dCtlEntry fields, the values they get set to, and what the values 



mean: 






dCtlFlags 


$0400 


DA can respond to Control calls 


dCtlDelay 


$0000 


Delay (in ticks) = 0, if timer update desired 


dCtlEMask 


$016A 


Events mask; enables octivateEvt, updateEvt, 






autoKey, keyDown, mouseDoum events for DA 


dCtlMenu 


$0000 


Menu ID associated with DA 



These are standard settings for most desk accessories. For many, they're the 
only settings you need, so that you won't need to initiafize these fields in your 
Open procedure. However, when in doubt, initialize the fields anyway and don't 
assume what values have or have not been set. 

Device Control Entry 

The operating system uses a data structure known as the device control entry 
(dCtlEntry) to keep track of device drivers and desk accessories. Each driver or 
DA has its own device control entry, which is passed as a parameter to its Open, 
Controly and Close procedures. The driver or DA can then set diflPerent fields to 
either tell the operating system how to handle it or keep track of information 
specific to itself between calls to its procedures. 
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The device control entry has the following declaration: 



type 

dCtlEntry 
record 



dCtlDriver 


: Ptr; 


dCtlFlags 


: Integer; 


dCtlQHdr 


: QHdr; 


dCtlPosition 


: Longint; 


dCtlStorage 


: Handle; 


dCtlRefNui 


: Integer; 


dCtlCurTicks 


: Longint; 


dCtlWindow 


: Ptr; 


dCtlDelay 


: Integer; 


dCtlEMask 


: Integer; 


dCtlMenu 


: Integer 



{ pointer/handle to the driver } 

{ status and control flags > 

{ driver I/O queue header } 

{ used by I/O drivers > 

{ handle to private storage > 

{ the driver's reference # } 

{ counter for system task calls > 

{ pointer to driver's window > 

{ # of ticks between Run calls } 

{ desk accessory event mask > 

{ menu ID associated w/driver > 



end; 



Don't feel overwhelmed if you don't understand what niany of those fields are 
for. Remember, this data structure isn't just used for desk accessories: It's also 
used for all device drivers, and so many of the fields aren't applicable to desk 
accessories. Other fields are used only by the operating system and don't need to 
be dealt with. Here's a brief explanation of the fields that do matter: 

• dCtlFlags: This two-byte field holds bits called flags, used to keep track of 
certain information about the desk accessory (or device driver). Seven bits of 
the upper byte are used to let the operating system know what kind of calls 
the DA (or driver) can or needs to respond to. Here are the flags and their 

functions: 

dReadEnabk 0100 Set if driver can respond to Read calls 

dWriteEnabk 0200 Set if driver can respond to Write calls 

dCtlEnable 0400 Set if driver can respond to Control calls 

dStatEnable 0800 Set if driver can respond to Status calls 

dNeedGoodBye 1000 Set if driver needs to be called before appli- 

cation heap is re-initialized 
dNeedTime 2000 Set if driver needs to be called on a periodic 

{=dCtlDelay) basis 

dNeedLock 4000 Set if driver needs to be locked in memory 



Two are of particular interest to the DA: bit 2 (dCtlEnable), which tells the OS 
if the DA can respond to Control calls, and bit 5 (dNeedTime), which is set if 
you want the DA to be called on a periodic basis (such as once per second). 
The lower byte has flags that the OS uses to keep track of the DA's (or driver's) 
status; they aren't of much concern here. 

• dCtlStorage: This handle (a pointer to a pointer) is used to keep track of a 
chunk of memory in which the DA can store any ^global" variables it needs. 
The standard approach is t(5 define a type of record whose fields comprise the 
variables desired. A call to NewHandle is used to do the allocation; after that, 
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type casting can be used to reference the record and its fields. More on this a 
Uttle later. 

• dCtlRefNum: Each DA (or driver) has a reference number used by the operat- 
ing system (and apphcation) to identify it. It is stored here, where it can be 
used by the DA to calculate (among other things) the appropriate ID for any 
resource (such as a menu) associated with the DA. This value is in the range 
— 13 to —32 and is related to the DA's resource ID (12 to 31) by the following 
equation: 

ID = -1 * (dCtlRefNum + 1) 

Even though the header PasDeskAcc sets the resource ID to 12, FONT/ 
DAMOVER might change that (to avoid duplicate IDs) when it installs your 
desk accessory into the SYSTEM file. You cannot and should not assume that 
your DA has a dCtlRefNum of — 13. 

• dCtlWindow: This field points to the window (if any) opened by the desk 
accessory. The operating system needs this information to pass certain window 
events to the current application, which is then responsible for handling them. 
The DA itself uses dCttWindow to set the window as the current grafport 
before doing anything in it. Also, if the DA does open a window, this field can 
be checked at the start of the Open procedure to screen out any attempt to 
open a DA that is already open. 

• dCtlDelay: This field tells the operating system how often to issue a run event. 
It's only effective if youVe set the dNeedTime bit in the dCtlFlags field. The 
value stored is in ticks (remember, 1 tick equals l/60th of a second), so that you 
would set this field to 60 if you wanted the DA to be called once a second. 

• dCtlEMask: This field tells the operating system what events the DA wants to 
respond to, just like the mask that an application passes as the first parameter 
in the procedure GetNextEvent, The event values should be set in Open, so 
that the operating system knows when (and when not) to call Control. The 
PasDeskAcc header initializes this field so that the desk accessory handles 
(just) the following five events: mouseDown, keyDown, autoKey, updateEvt, 
and octivateEvt 

• dCtlMenu: If the DA has a menu associated with it, dCtlMenu should be set to 
that menu's ID. Resources associated with a desk accessory must have IDs 
that fall within a specific range of values. More on this in "Setting Up the 
Resources" several pages ahead. 

The same device control entry is passed to all three procedures {Open, Con- 
trol, and Close), so information set in one procedure can be read or modified in 
another. For example, the DA might use dCtlWindow to point to the window 
opened in Open, set that window as the current grafport in Control, and close 
and dispose of that window in Close. 
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Global Variables 



Now you need to learn about the other major data structure in your desk acces- 
sory: your global variables-equivalent record. Since you can't actually declare 
any global variables, this record is designed to hold all the information you want 
to preserve between calls to your desk accessory. Your first step is to define this 
record as a data type, in the following manner: 



end; 

DAGlobaisP - '^DAGlobals; 
DAGlobalsH = *DAGlobalsP; 

This record (DAGlobals) assumes that you have four ^global'' variables that you 
want to maintain: theMenu, theString, thePlace, and CHandle, (NOTE: This is 
just an example. You do not have to have fields with those names or of those data 
types; instead, your global record should reflect what the DA you re writing 
needs.) You Ve also declared a data type that's a pointer (DAGlobaisP) to this 
type of record and another that's a handle (DAGlobalsH) to the same type of 
record. The pointer is actually just an intermediary step, since you can't directly 
declare a handle (such as DAGlobalsH = ^ ^DAGlobals). 

The example shows you how to define the proper data type, but not what to do 
with it. You need to set aside a block of memory large enough to contain a record 
of this type, then save a handle to that block in the device control entry. The next 
section shows you exactly how to do that. 

Initialization 



When a desk accessory is launched and its Open procedure is called, the proce- 
dure's only parameter is the device control entry that the operating system has 
now associated with that DA. The Open procedure then takes care of three major 
tasks: setting the fields in the device control entry; allocating and initializing any 
global variables; and setting up any resources, such as windows, dialog boxes, 
menus, and so on. The first task is unique to the desk accessory (or driver), but 
the next two are similar to those found in the initialization procedure of any Mac 
application. These tasks overlap, but they're worth discussing individually. 
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type 



DAGlobals 
record 

theHenu 
theString 



: HenuHandle; 

: String; 

: Point; 

: CarsHandle 



thePlace 
CHandle 



Setting Up the Device Control Entry 



This record is passed to Open as a parameter of type dCtlEntry; we'll assume 
that the parameter is named Device. You need to set certain fields in Device, 
either for the use of the operating system or for your own use later on. Following 
are the fields you may need to initialize, with some guidelines on how to do so. 

The field dCtlFlags lets the operating system know what type of calls it can 
make to your desk accessory. The flag dCtlEnable (bit 2 in the upper byte) is 
already set, thanks to PasDeskAcc, However, if your desk accessory needs to 
update something periodically, set the flag dNeedTime (bit 5 in the upper byte). 
The sample desk accessory (MYDA) moves a string of text a little bit down the 
window every half a second, so it sets this flag. The constant dNeedTime is 
defined in the program as $2000, again corresponding to the proper bit; a logical 
OR can be used to set this bit: 

dCtlFlags := dCtlFlags or dNeedTiie; 

If this bit is set, then the operating system makes calls of the type accRun to 
Control on a regular basis. Note that these calls are made in addition to any 
control event calls made as a result of setting dCtlEnahle. 

If your DA has requested periodic calls to Control, you must also specify how 
often those calls occur. You do this by assigning a value to the field dCtlDelay. 
This field is initialized to 0 by PasDeskAcc. This means that the operating system 
will make calls to Control as often as it can if you have set the dNeedTime bit in 
dCtlFlags. Any value greater than 0 defines how long (in ticks) the operating 
system will wait before making another accRun call to Control; however, this 
delay will not stop the OS from making other control calls to Control. Since a tick 
is l/60th of a second, setting dCtlDelay to 60 asks the operating system to call 
your DA once a second. 

You may need to modify dCtlEMask, which serves as an event mask for your 
desk accessory. The event types include mouse down, key down, auto key, 
update event, and activate event. You can use the predefined constants 
{mouseDown, keyDown, autoKey, updateEvt, and octivateEvt) and the logical 
OR instruction to set up the mask, as in: 

Device. dCtlEMask := mouseDown or updateEvt or activateEvt; 

By the way, Inside Macintosh states that you should never request mouseUp 
events if your desk accessory has a window, though it fails to explain exactly why. 

There are three more fields that you may want or need to initialize: 
dCtlStorage, dCtlWindow, and dCtlMenu. The first is used to keep track of any 
private (global) data storage your desk accessory needs; the second is a pointer to 
the window that your DA opens (if it opens one); and the third contains the ID 
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number of the menu that your DA creates (if it creates one). The next two sec- 
tions explain more about these fields. 

Setting Up the Global Variables 



Back in the section on global variables, you learned about how to define the data 
types you need for your global variables. You defined a record (DAQlobals) 
whose fields corresponded to the variables you needed, and a handle 
(DAGlobalsH) to that type of record. However, if you remember, these are all 
just data types; no actual variables have been declared, and no storage has been 
set aside. Instead, in the Open procedure of your desk accessory, you should 
have the following statement: 

Device. dCtlStorage := NewHanaie(SizeOf (DftGlobals) ) ; 

The OS function NewHandle returns a handle to a chunk of memory; the 
parameter passed specifies the size in bytes. The built-in function SizeOf returns 
the size in bytes of the data type or variable passed to it. This statement allocates 
memory equal in size to a variable of type DAGlobals and assigns a handle to that 
memory to the field dCtlStorage. 

Fine, the memory is set aside, and dCtlStorage points (indirectly) to it. Now, 
how do you use this memory as a global variable? Use the following statements: 

RLock(DeTlce. dCtlStorage) ; 

with DftGlGbalsH(Device. dCtlStorage)** do 

begin 

{ use theHeno/ etc.r as desired > 
end; 

HUnLock( Device. dCtlStorage) ; 

The OS procedure HLock ensures that the operating system (which has the 
ability to move chunks of memory around) doesn't move your chunk until you're 
done using it. The with statement uses a form of type castings that is, converting 
one data type into another. The expression DAGlohal8H(Demce, dCtlStorage) 
takes the generic handle dCtlStorage and converts it to the data type 
DAGlobalsH, which is a handle to a record of type DAGlobals. The two pointer 
symbols or carets (^^) mean that you are now directly referencing a record of 
type DAGlobals, so that you can freely refer to the fields (theMenu, theString, 
and so on) by their names. When you re finished, the OS procedure HUnLock 
tells the OS that it is once again free to move that chunk of memory around-^ 
until the next time you want to use it. 
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Setting Up the Resources 



Almost all desk accessories open a window or dialog box of some sort, since they 
need an area on the screen in which to perform their function. In addition, other 
resources — ^menus, strings, cursors, icons — ^may be associated with the desk 
accessory. As with an application, resources can be handled two ways: either by 
defining them in a resource file, or by building them right within the initializa- 
tion section. For example, you can open a window by using GetNewWindow to 
read in the values from the resource fork (assuming that you Ve defined it there), 
or by using NewWindow and passing all the specifics as parameters. 

Resource IDs 

Like an application, a DA may have resources associated with it. Since the codes 
of all DAs and all their resources are stored in the SYSTEM file, the operating 
system needs a mechanism to identify which resources are related to a particular 
DA. Therefore, the operating system requires all DA-related resources to have 
IDs that follow this binary pattern: 

11 DDO rrrrrr xxxxx 

where rrrrrr is the DA's resource ID (12 to 31), and xxxxx is a number deter- 
mined by you. This gives you only 32 diflFerent resource ID values for a given 
desk accessory. However, since resources of diflFerent types (such as MENU and 
WIND) can have the same ID, this actually means that you can have up to 32 
instances of each resource type in your resource file. 

The PasDeskAcc header fixes your DA resource ID at 12. This means that the 
resource ID values in your resource file must be in the range $G180 to C$19F, 
which corresponds to —16000 to —15969. 

This numbering system is fine for compihng your desk accessory, but a compli- 
cation occurs when you move it into the SYSTEM file, using FONT/DA 
MOVER. FONT/DA MOVER changes the resource ID of your DA if an existing 
DA in your SYSTEM file has the same ID. Similarly, it adjusts the IDs of all 
related resources by changing the (rrrrrr) field to the DA's new resource ID 
value. This means that you can't use hard-coded constant values for resource IDs 
in a DA. Instead, you must calculate resource IDs at run-time. 

You can calculate the resource IDs using the field dCtlRejNum. Remember 
that dCtlRefifum and the desk accessory's resource ID are related by the expres- 
sion 

resID « -1 » (dCtlRefHuffl+l) 
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Therefore, the equation for calculating the starting resource ID within your 
desk accessory is 

startID - $CDDD - 3E#(dCtlRefNuin+l) 

A convenient place for storing this value is the dCtlMenu field, if you have a 
menu; this should be its resource ID anyway. If you don't have a menu, then this 
field should be set to 0, and you'll have to calculate the value as needed or store it 
as a field in your globals record. 

Opening the Window 

Most desk accessories open a window of some kind, which requests or displays 
information. The system must tell the current application, which needs to han- 
dle many window events for the desk accessories, about this window. This is 
done via a pointer to the DA's window, which is stored in the field dCtlWindow, 
Furthermore, the window's windowKind field must be set to the DA's reference 
number (dCtlReJNum), All this involves some type casting (the programming 
equivalent of hand signaling), so that the compiler thinks dCtlWindow is first of 
type WindowPtr, then of type WindowPeek. The following statements open a 
DA*s window: 

WindowPtr ( dCtlWindow ) : = GetNewWindow ( dCtlMenu , NIL , Pointer ( -1 ) ) ; 
WindowPeek( dCtlWindow)'*. WindowKind := dCtlRefNum; 

The first reads the window data in from the resource fork and creates it; the 
second sets' the windowKind field in the corresponding window record. 

Later on in Open, the window's contents should be set up as needed. The 
sequence of code should look something like this (assuming that SavePort is a 
variable of type GrafPtr): 

GetPort ( SavePort ) ; { save cur port > 

SetPort(GrafPtr(dCtlWindow)); { get our window > 
{ do your window text or drawing > 

SetPort( SavePort) { restore grfprt } 

This code saves the current grafport, then sets up the DA's window so that it 
can be written to. After you've set up the window, the current grafport is 
restored and continued. 
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Setting Up a Menu 



A desk accessory can have a menu associated with it. You Ve already seen how to 
calculate a DA's resource ID; having done that, you can read the DA in and set it 
up with the following statements (assuming theMenu is a variable of type 
MenuHandle): 



The first statement reads the menu in from the resource fork, while the second 
verifies that the menu record has the correct ID. This is necessary because some 
resource-moving utilities don't properly name the resource ID within the menu 
itself The last two statements put the menu at the end of the current menu bar, 
then redraw the bar so that the menu shows up. 

It is possible for a desk accessory to set up more than one menu. Should you 
choose to do so, however, you should create an entirely new menu bar and swap 
menu bars as the desk accessory is activated or deactivated (see Inside Macin- 
tosh, Volume 1, Chapter 14, for more details). 

Opening Other Resources 

You can read in other resources in a similar fashion. One example would be to 
read in a new cursor from the resource file for use when the desk accessory is 
active and the cursor is over its window. Other resources, such as strings and 
patterns, can be read in the same way. 

Handling Multiple Calls to Open 



A desk accessory can be launched more than once. That is easily illustrated by 
starting one up, then pulHng down the Apple menu. The desk accessory remains 
on the menu, just waiting to be selected again. You can prevent a new window 
(or whatever else) from being created each time the desk accessory is selected 
from the Apple menu. 

The key is to realize that the same Open routine is called with the same device 
control entry record (Device). By checking the fields in Device, you can tell if 
Open is being called again. For example, a test is performed to see if dCttWin- 
dow is nil: 

procedure Open; 



theMenu := GetMenu(dCtlMenu) ; 
theMenu'"'. lenuID := dCtlMenu; 
InsertMenu ( theMenu, D) ; 
DrawMenuBar; 



{ 



get menu hndl } 

verify ID val } 

{ add to bar > 

{ redraw bar > 



var 



SavePort 
TempVal 



: GrafPtr; 
: Integer; 
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begin 
with Device do 

if dCtlWindow = nil then { make sure not already open > 

begin 

{ do all the initialization } 
end 

end; { of procedure Open > 

If dCtlWindow equals is nil, then the initialization occurs; otherwise, Open 
knows that the desk accessory already has a window open (and, presumably, has 
everything else set up as well), and so skips all the initialization steps. 



Event Handling 



Desk accessories, like Mac applications, are event-driven programs. In fact, they 
are more event-driven than applications are, since they are only called when the 
operating system has some event it thinks the desk accessory should handle. 
When that happens, the DA calls the procedure Control, passing it three param- 
eters: Device, Code, and Param, Device is the same old device control entry 
record, which you'll need to access its fields, as well as any global variables. Code 
is an Integer value that tells Control what type event the OS wants it to handle, 
while Param is a Longint value that contains (or points to) any parameters associ- 
ated with the particular event. 



The Control Procedure 



Here's an example of what the Control procedure could look like: 

procednre Control(var Device: DCtlEntry; Param: Longint; Code: Integer); 
forvard; 

procedure Control; 
var 

SavePort : GrafPtr; 
begin { niain body of proc Control } 

with Device do 

begin { access DCtlEntry } 

HLock(dCtlStorage) ; { freeze reloc block } 

with DAGlobalsH(dCtlStorage)'^* do 
begin { access globals } 

GetPort(SavePort) ; { save current port } 

SetPort(GrafPtr(dCtlWindow)); i switch to ours > 

case Code of 

accEvent : HandleEvent(EventRecP(Paraia) ) ; i deal with event } 
accRun : HandleTick; { deal with timer } 

accCursor : CursorAdjust; { change cursor } 

accMenu : HandleMenu { Param ) ; { item from menu > 
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accUndcAccClear 

: HandleEdit(Code) ; { standard edit commands > 
goodBye : Close(Device) { about to shut down > 

end; 

SetPort(Sa7ePort) { restore old port > 

end; 

HUnLock(dCtlStorage) { unfreeze rel block > 

end 

end; { of proc Control > 

Control first locks down the block that dCtlStorage points to, to prevent the 
operating system from moving it while it's in use. It then sets up its window as 
the current grafport and handles the event code (Code) that the operating sys- 
tem has passed to it. Here's a description of the event codes, which should have 
been declared as constant values at the start of your desk accessory: 

• accEvent (64); Some system event (mouseDown, for example) has occurred, 
and the desk accessory must handle it. Param points to a record of type 
EventRecord; type casting is used to pass that record as a parameter to 
HandleEvent. 

• accRun (65): It's time for the periodic update requested by the DA via the 
dCtlFlags and dCltDelay fields. You should then do whatever it was you 
wanted the DA to do on a periodic basis. 

• accCursor (66): It's time to change your cursor, if you want a different cursor 
when your desk accessory is active and the cursor is over its window. This 
parallels putting a call to a Cursor Adjust procedure in the main event loop of a 
Mac application. 

• accMenu (67): The user has just selected an item from the DA menu(s). Param 
now contains the menu and item values in its high and low words, respec- 
tively. You should pass it to a menu-handling routine. 

• accUndo (68), accCut (70), accCapy (71), accPaste (72), accClear (73): The user 
has passed a value in the set [1,3. .6] to the SystemEdit function, signifying that 
the Undo, Cut, Copy, Paste, or Clear command has been selected from the 
Edit menu. You should take appropriate action, if there is any. The gap 
between accUndo and accCut accounts for the line separator. 

• goodBye (—1): The system, for whatever reason, is about to shut the desk 
accessory down and free up the memory it uses. You should call Close to do all 
your cleaning up. 

This version of Control handles all possible messages from the operating sys- 
tem, but your desk accessory may not need to handle that many. If it doesn't 
have a menu, you can drop the check for accMenu; likewise, you can ignore any 
or all of the editing commands if they don't apply to your desk accessory. In 
addition, if you don't care about the cursor, you can remove the check for 
accCursor. If you haven't requested a periodic update, you don't need to worry 
about accRun. In short, the only two messages you must at least handle are 
accEvent and goodBye. 
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Event-Handling Routines 



The HancUeEvent procedure looks very much like its counterpart in a Mac appU- 
cation: 



procedure Han<!leEveiit(EPtr 
begin 
case EPtr*.What of 



EventRecP) ; 



DoMouseDown(EPtr'') ; 
DoKeyPress(EPtr*); 
DoKeyPress(EPtr*) ; 
DoUpdate; 
DoActivate(EPtr*) 



{ mouse button pushed } 

{ key pressed down > 

{ key held down } 

{ window need updating > 

{ activate/deactivate } 

{ of proc HandleEvent > 



mouseDown 
keyDown 
autoKey 
updateEvt 
activateEvt 
end 
end; 

It should handle the five basic events: mouseDown, keyDown, autoKey, 
updateEvt, and activateEvt. However, it probably won't have much to do for 
most events, since a lot of the DA's event handling is done by the current appli- 
cation or by the operating system itself 

A mouseDown event is particularly simple to handle, since all the varieties 
except for inContent are dealt with by the application or the OS. Furthermore, 
you don't need to check to see if the event happened within the DA's window, 
since the event wouldn't have been passed to the DA otherwise. Here's a sample 
procedure: 

procedure DoMouseDown(theEvent:EventRecord) ; 
var 

MLoc : Point; 

begin 

with Device, DAGlobalsH(dCtlStorage)'** do 
begin 

thePlace := theE vent. Where; 
GlobalToLocal{thePlace) ; 
UpdateWindow 
end 
end; 



{ find where click was 
{ convert to local coord 
{ and update window 

{ of proc DoMouseDown } 



The location of the event, in global coordinates, is found in the field Where of 
the event record; you can convert it to local (window-based) coordinates by pass- 
ing it GlobalToLocal. UpdateWindow, a user-defined procedure, is called to 
allow the desk accessory to respond to the mouse click. 

The keyDown and autoKey events should be handled as you would in a Mac 
application. You should check (as usual) to see if the event is a menu command 
and, if so, handle it accordingly; otherwise, do whatever the DA should do if 
someone just presses a key. Be aware, though, that the MenuKey function 
doesn't work properly within a desk accessory, so you'll have to do the conversion 
by hand, probably by using a case statement. 
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Here's an example: 

procedure DoKeyPress(theEveat : EventRecord) ; 
var 

Ch : Char; 
begin 

with theEvent/ Device, myGlobalsHCdCtlStorage)** do 
begin 

Ch := Chr(Message and charCodeMask) ; i get character pressed } 
if (modifiers and cmdKey) <> D then { check for command key > 
begin 

if Ch in ['a'..'z'] then 

Ch := Chr(0rd(Ch)-3E) ; { convert to uppercase > 

case Ch of 

'Z' : HandleEdit(accUnDo) ; 
'X' : HandleEdit(accCut); 
'C : HandleEdit(accCopy) ; 
'V : HandleEdit(accPaste); 

{ handle other menu command, if the DA has a menu } 

end 
end 

else SysBeep{l) { do something in response to the key > 

end 

end; { of procedure DoKeyPress > 

HandleEdit, you may remember, is a user-defined procedure that takes care of 
the standard editing commands: Undo, Cut, Copy, Paste, and Clear. Its struc- 
ture should be something like this: 

rocedure HandleEdit (ECode : Integer); 
egin 

case ECode of 

accDnDo : { handle Undo command }; 

accCut : { handle Cut command >; 

accCopy : { handle Copy command }; 

accPaste : { handle Paste command }; 

accClear : { handle Clear command } 
end 

end; < of procedure HandleEdit } 

The comment sections should be replaced by whatever code is needed to 
handle that particular command, even if it's just a beep (SysBeep(l)). 

The updateEvt event should also be handled as in a Mac application. It means 
that the window has just been moved or uncovered and needs to be redrawn, 
with the updating code bracketed between calls to BeginUpdate 3Lnd EndUp- 
date. For example: 

procedure DoUpdate; 
begin 

with Device, myGlobalsH(dCtlStorage)'''* do 
begin 

BeginUpdate(GrafPtr(dCtlWindow) ) ; 
{ perform DA window redraw > 
EndUpdate { Graf Ptr ( dCtlWindow ) ) 
end 

end; { of procedure DoUpdate } 
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Unlike the DoUpdate routine in Chapter 9, this one has no calls to GetPort 
and SetPort. Th3±'s because those calls have already been made back in the main 
body of the Control procedure. 

The DoActimte routine doesn't need to do window selection or similar tasks; 
that's handled by the current application. It does, however, need to take care of 
any functionality associated with whether the DA is active or inactive. The fol- 
lowing procedure, DoActivate, enables or disables a DA's menu, depending on 
whether the DA is being activated or deactivated: 

procedure DoActivate (theEvent : EventRecord) ; 
begin 

with theE vent, Device, niyGlobalsH(dCtlStorage)''* do 
begin 

if Odd(inodifiers) then 

EnableIteBi(theMenu,0) { enable entire menu } 

else DisableIteni(theHenu,0) ; i disable entire menu > 
DrawHenuBar 
end 

end; { of procedure DoActivate > 

HandleTicks does pretty much as described: It takes whatever periodic action 
the user wants it to. In the following example, it moves the desired location of a 
string of text down, then calls UpdateWindow to draw the string in the new 
location: 

procedure HandleTicks; 
begin 

with Device, niyGlobalsH(dCtlStorage)'*'* do 
begin 

thePlace.V := (thePlace.V + 5) mod 2DQ; { do wraparound at bottom } 
UpdateWindow 
end 

end; { of procedure HandleTicks } 

Likewise, Cursor Adjust (if present) tests for the current location of the mouse 
and sets the cursor accordingly. In the procedure below, a cursor defined in the 
resource file is read into a global variable and is used whenever the mouse is over 
the da's window: 

procedure CursorAdjust; 
var 

MLoc : Point; 
begin 

with Device, DAGlobalsH(dCtlStorage)**, WindowPeek{dCtlWindow)'* do 
begin 

GetMouse(MLoc) ; 

if PtlnRect{ MLoc, Port. portRect) then { if mouse over DA window } 
SetCursor(CHandle**) { then use DA 's cursor > 

else Initeursor { else use default cursor } 

end 

end; { of procedure CursorAdjust > 

Type casting the window pointer (dCttWindow) is done in order to get the 
window's rectangle (Port.portRect). 
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Menu Handling 



If your desk accessory has its own menu, you need to be able to handle the 
commands as they come in. They'll be signalled by the Code parameter {Code = 
accMenu) in the Control procedure, instead of by a mouseDown event, and the 
menu information is passed in the Faram parameter. Your menu-handling rou- 
tine (HandleMenu) is called directly from Control and might look like this: 

procedure HandleMenu (Menulnfo : Longint); 
var 

Menu,Itei : Integer; 
begin 

if Menulnfo <> Q then 

with Device, DAGlobalsH(dCtlStorage)*'* do 

begin 

Item := LoWord( Menulnfo) ; 
case Item of 

1 : { handle first item in menu >; 

E : { handle second item in menu >; 

{ and so on > 
end 
end; 

HiliteMenu(O) 

end; { of procedure HandleMenu > 

It is possible to implement more than one menu in a desk accessory, by saving 
the current menu bar and creating an entirely new one. In that case, you should 
make HandleMenu look like the version in a regular Mac application; have a case 
statement based on the menu ID, then internal case statements for the items of 
each menu. 



Support Routines 



The purpose of your desk accessory is, of course, to do something, which the 
support routines help you accomplish. These are the procedures and functions 
that your event-handling routines call, just as in a regular Mac application. Most 
look as they would in a regular Mac application, the major diflFerence being that 
many probably have a main body that looks something like this: 

procedure Whatever ( { any parms } ) ; 
•( any local declarations > 
begin 

with Device, DAGlobalsH(dCtlStorage)** do 
begin 

{ do whatever needs to be done } 
end 
end; 
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These support routines are probably located in one of two places. First, they 
may be declared within one or more of the main procedures, such as Control, If 
they are included inside the procedure Control, this makes all those routines 
local to (that is, only able to be called by) Control. This approach allows all those 
routines access to Device, which is one of Contrors parameters and therefore is 
visible to all local routines. 

The other approach is to declare some (or all) of the support routines to be 
global; that is, to declare them outside of and before the procedures Open, Con- 
trol, and Close, That way, these routines may be called by any or all of those 
three major procedures. The disadvantage is that Device must be explicitly 
passed to the support (and event-handling) procedures by the calling procedure. 



Closing Down 



Several things can bring about the termination of a desk accessory. An applica- 
tion can explicitly terminate the DA by cdlhng CloseDeskAcc. It should do this, 
for example, when handling the inGoAway version of the mouseDown event in a 
desk-accessory window. Second, the desk accessory may want to terminate itself, 
perhaps due to insufficient or missing resources. Third, the operating system 
may need (or want) to shut down the DA. In any case, the DA should be able to 
make a graceful exit, cleaning up after itself as best it can. 

To do all this, the desk accessory uses its Close procedure. This is the proce- 
dure the operating system calls when it (or the application it*s running) wants to 
close down the DA. The close routine should get rid of the DA's window (if it 
has one), delete its menu (if it has one), and free up any space pointed to by 
Device. dCtlStorage. The calls to do all this are standard Toolbox and OS calls. 
Here's an example: 

procedure Close; 
var 

MHandle : MenuHandle; 

begin 

with Device, DAGlobalsH{dCtlStorage)** do 
begin 

DisposeWindow(GrafPtr{dCtlWindow) ) ; 
DeleteMenu(dCtlMenu) ; 
DisposeMenu(theMenu) ; 
DrawMenuBar; 

DisposHandle(dCtlStorage) ; 
dCtlWindow := NIL 
end 
end; 



{ get rid of window } 

{ reiove from bar } 

{ get rid of menu } 

{ and update menubar } 

{ get rid of globals } 

{ clear window ptr } 

{ of procedure Close > 
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If your DA has any data (such as text) that has been entered by the user, you 
may want to ask the user whether or not to save it to disk. At this point, there's 
no way to avoid having the desk accessory terminated, but you can at least mini- 
mize the eflFects. 

In some cases, the procedure Control gets the notification that the application 
heap is about to be re-initialized. This happens if two conditions are met: First, 
the desk accessory has not been locked in RAM; second, the DA has specifically 
requested a goodBye event. In such a case, you should have a goodBye entry in 
the main case statement in the procedure Control, and that entry should call 
Close. 



Compiling and Installing a Desk Accessory 



Writing a desk accessory doesn't do much good unless you know how to correctly 
compile and install it. In this section, you'll learn how to compile MYDA, 
a sample desk accessory on your Turbo Pascal disk, and install it into your 
SYSTEM file. 



MYDA; A Desk-Accessory Template 



MYDA consists of three source files: 

• MYDA.PAS contains the global declarations, as well as the Open, Control, and 
C lose procedures . 

• MYDA.INC contains the event-handling and support routines. The include 
{$1} directive for this file is just inside the Control procedure. 

• MyDA.R contains the resources — window, menu, and cursor — ^used by 
MYDA. 

MYDA opens a window, creates a menu, and sets up its own cursor. It then 
writes a text string into its window and starts moving the string down. When it 
reaches the bottom of the window, it starts over at the top. By moving the cursor 
to any part of the window and clicking, you can move the string to that point; it 
continues to move down from there. 

The three items in the DA's menu all change the string being moved. Like- 
wise, the editing commands don't edit the string at all; they just set it equal to 
the corresponding command (Cut, for example), so that you can see where you 
would need to put the code to handle that command. 
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Finally, you can change the string by typing on the keyboard, though you first 
may want to use the backspace key to delete whatever text is already there. 

Compiling MYDA 



Compiling MYDA is a two-step process. First, just as with a Mac application, 
you need to ^compile" the resource file (MYDA.R) using RMAKER. Start up 
RMAKER by double-clicking on its icon from the desktop (or by selecting it from 
the Transfer menu). Open the file MYDA.R, using the file selection box that 
RMAKER brings up. When it is done, the file MYDA.RSRC is created. You can 
now go back to Turbo Pascal; either push the Quit button (to get back to the 
desktop first) or use the Transfer menu to go directly back into Turbo Pascal. 

From Turbo Pascal, open up MYDA. PAS, If you didn't transfer over from 
RMAKER, you can do this either by double-clicking on MYDA. PAS, or by dou- 
ble-clicking on Turbo Pascal and using the Open item of the File menu to find 
and open the file. Having done that, go over to the Compile menu and select the 
To Disk option (or type (^JE^). The result is the file MYDA, which contains the 
machine code of the desk accessory in the proper format. 

Installing MYDA 



Having successftiUy compiled MYDA, you need to install MYDA into your sys- 
tem file (named SYSTEM). Which brings up an important warning: Moving 
desk accessories in and out of system files can, in some cases, corrupt them (the 
system files, that is). Likewise, a desk accessory with significant bugs can also 
trash your system file. So, before going any farther — ^before doing anything else 
at all — make a copy of the system (boot) disk onto which you plan to install 
MYDA and use that copy, putting the original away in a safe place somewhere. 

If you are using a hard disk, be even more careful. Back up the entire hard 
disk once, just so you can restore it should anything terribly catastrophic occur. 
(You back up your hard disk periodically, anyway, right?) Then back up your 
SYSTEM folder and/or volume on the hard disk, so that you can restore just that, 
if necessary. This may seem like a lot of unnecessary work, but should anything 
really bad happen, you'll be glad you took the time. 

Do all that before you go any farther. Everything backed up? Now launch the 
program FONT/DA MOVER, which has a little truck icon, by double-clicking it 
(or by selecting it from the Transfer menu within Turbo Pascal). A dialog box con- 
taining two windows appears. The window on the left automatically opens the 
current SYSTEM file; the window on the right is empty. The box comes up in 
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Font mode, so click on the Desk Accessory button under the Font button at the 
top of the screen. The left window now displays all the desk accessories currently 
installed in the SYSTEM file. If MYDA (a previous version) is already there, 
remove it: point at it with the cursor, click the mouse button, then click on the 
Remove button located between the two windows. 

You now need to open the file MYDA to copy your newly-compiled version 
into the SYSTEM file. Click on the Open button below the right window. This 
brings up a file selection dialog box. Find the file MYDA (you might have to click 
on the Drive button to look on different disks or volumes) and select it by double- 
chcking on it. The file selection box goes away, and MYDA appears in the right 
window. Click on it once to select it, then click on the ((Copy(( button located 
between the two windows to copy MYDA into the SYSTEM file. (This may take 
a few minutes, especially if you re working on floppy disks.) When the transfer is 
done and the cursor changes back from a watch to an arrow, select the Close 
button under each of the two windows. Then select the Quit button to leave 
FONT/DA MOVER and go back to the FINDER. 

If you installed MYDA in the current SYSTEM file, MYDA should appear in 
the Apple menu. Full it down and, if it's there, select it. A window (labeled My 
DR) appears on the right side of the screen. The phrase Hello, world displays 
near the top of the window and starts moving down. Also, the DA menu is added 
to the menu bar. If you select any of the items in it, the corresponding string 
replaces the string in the window. 

Likewise, if you select any of the top five commands in the Edit menu, that 
command name replaces the string in the window. When you move the cursor 
over the DA's window, it turns into a smiley face.'' Click the mouse and the 
string moves to where the cursor is, then starts moving down again. If you click 
on the title bar of another window, de-selecting the DA window, the DA menu is 
disabled, but the string keeps moving down. You can reactivate the DA window 
by clicking on it again; you can move it around using the drag bar at the top; and 
you can make it go away by clicking on the Close box. 

If you want to remove MYDA from your SYSTEM file, run FONT/DA 
MOVER again. Select the Desk Accessory button at the top. Look through the 
list of DAs until you find MYDA. Click on it to select it, then click on the 
Remove button to get rid of it. Click the Close button under the left window to 
close the SYSTEM file, then click the Quit button to get out of FONT/DA 
MOVER. MYDA should now be gone from the Apple menu. 
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Writing Your Own Desk Accessory 



MYDA was created to help you write your own desk accessories. It's a very basic 
template that contains most of the event-handling code you'll need; in fact, it 
probably contains more than you need, since it attempts to handle all situations. 
If you print it out and study the code, you may get a better understanding of desk 
accessories than you would reading the sparse and sometimes cryptic comments 
in Inside Macintosh, 

The first step in writing your own desk accessory should be to make some 
modification to MYDA (which you know works). Before doing this, back up the 
original MYDA files so that you don't modify or destroy the originals. Or make 
copies of them and rename the copies to something like NEWDA. If you do this, 
however, be sure to make corresponding changes to the {$R} and {$1} directives 
inside the .PAS file. You'll probably want to change the name in the program 
header at the top of the .PAS file, as well. And you'll need to change the name of 
the resource output file (at the top of the .R file). 

To make the DA smaller, you can eliminate the smiley cursor by doing the 
following steps. Make a deletion in each of the three files (which, for now, 
we'll assume are called NEWDA. PAS, NEWDA. INC, and NEWDA. R). In 
NEWDA. R, delete the cursor definition, which is the last resource in the file 
and starts with the line Type CURS = GNRL. In NEWDA.INC, delete the proce- 
dure CursorUpdate, In NEWDA. PAS, make changes to both the Open and 
Control procedures: In Open, delete the line CHandle : = GetCursor(dCtlMenu) ;. 
In Control, delete the line in the case statement that says accCursor : CursorUp- 
date ; . You could also delete the field CHandle from the data type DAGhbals. 
Now, run RMAKER, Turbo Pascal, and FONT/DA MOVER as described in the 
previous section. When you run NEWDA, you'll notice that the cursor no longer 
changes to a smiley face when it is moved over the DA window. 

In a similar fashion, you can delete other portions of MYDA. For example, you 
could stop handling the Edit commands: Delete the HandleEdit procedure, 
move the calls to HandleEdit in DoKeypress, remove the call to HandleEdit in 
HandleMenu, and remove the line accUndo. .accClear : HandleEdit(Code) ; in 
Control. Likewise, you could remove the DA menu by deleting the menu from 
the resource file and eliminating the code to handle it from the source code files. 

Another sample desk accessory, after which MYDA was patterned, is 
CLOCK. PAS. This DA brings up an analog clock — ^with second, minute, and 
hour hands — ^and updates it as you watch. It is well worth studying, since it 
shows a working DA that does only as much event handling as it has to. Between 
CLOCK. PAS and MYDA, you should be able to design and implement the desk 
accessory you want to write. 
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More Beferences 



There is more to writing desk accessories than is discussed here. The primary 
source, as always, is Inside Macintosh, especially Vol. I, Chapter 14, **Desk Man- 
ager,** and Vol. II, Chapter 6, **Device Manager.'' However, the information in 
Inside Macintosh isn't comprehensive, and it assumes that your desk accessory is 
written in assembly language. An excellent supplement is MacTutor, a magazine 
devoted to Macintosh programming. Back issues of MacTutor contain a number 
of articles on desk accessories, and while many of the DAs discussed are written 
in C or assembly language, almost all of the articles contain information worth 
knowing. 
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CHAPTER 



Using UNITMOVER 



When you write units, you want to make them easily available to any programs 
that you develop. You do this by moving the units into the TURBO file. You can 
then pull the TURBO file units back out to fix code errors or to make the 
TURBO file smaller by using the application UNITMOVER. 

Chapter 7 explains what a unit is; Chapter 8 tells how to create your own 
units. This chapter shows you how to use UNITMOVER to move units between 
two files. 



Moving Units 



Normally, when you write your own unit, it gets saved out to a file; to use that 
unit, you have to specify the file name in a {$U {filename)} compiler directive. 
You may have noticed, though, that you can use the standard Turbo Pascal units 
without giving a file name. That's because these units are stored in the Turbo 
Pascal application file, that is, in the actual editor/compiler file named TURBO 
that shows up on your desktop with the icon of a hand waving a checkered flag. 
Since the units are in that file, any program can use them without a {$U} direc- 
tive. 

UNITMOVER is used to move your units in the TURBO file, so that they can 
be used as easily as the standard units. 
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UNITMOVER is a stand-alone application; its icon appears as a standard Mac- 
intosh application icon (a hand writing on a piece of paper). To use it, point the 
mouse at it and double-click. Or, if you re inside Turbo Pascal, exit Turbo Pascal 
and get into UNITMOVER by selecting it from the Transfer menu at the far right 
end of the menu bar. A third option is to double-click on any unit code file, that 
is, the file produced by compiling a unit to disk. 

However you get into it, UNITMOVER brings up a display like that shown in 
Figure 11-1. 

Turbo Pascal® Unit Mouer Uersion 1.00R ©1986 Borland International | 



[ Open... ] 



Help 
Quit 



[ Open^ 



.2: 



Figure 11-1 The UNITMOVER Screen 



If you've ever used the FONT/ DA MOVER utility, you'll feel at home here, 
for the display and functions are very similar. 

Since UNITMOVER's purpose is to move units between two files, first select 
and open those two files. Click on the Open button beneath the left-hand win- 
dow. A standard file selector display appears; you then select the file. 
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Figure Jl-2 The UNITMOVER FUe Selector Box 

The resulting display, with the file open on the left-hand side, appears in 
Figure 11-3. 

I Turbo Pascal® Unit Mouer Uerslon I.OOR ©1986 Borland International I 
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Figure JJ-3 UNITMOVER with a File Open 

You should do the same thing on the other side (that is, click on the right-hand 
window's Open button), so that your source file (the one youVe copying from) is 
open on one side, and your destination file (the one you're copying to) is open on 
the other. If you want to install a unit into Turbo Pascal, then one of the two files 
has to be TURBO. 

Select the unit to be copied by finding it in the appropriate display (using the 
scroll bar if necessary) and clicking on its name. You can select more than one: 
Hold down and click on the name of each unit to be copied. 
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Figure 11-4 UNITMOVER with Units Selected 

As you select each unit, information concerning it appears in the area at the 
bottom of the screen. The information box shows its size, the other units it uses 
(so that you can copy them as well, if necessary), and if the unit is not in the 
destination file. 

To copy the unit(s), just click on the Copy button located in the top center 
portion of the screen. A copy of the selected unit(s) is placed in the other file. 
Make sure you have enough room to receive them. 

Deleting Units 



You can remove units from a file using the same method. Open the file, select 
the units, and click on the Remove button. The units are deleted from the file. 
Be aware that they are gone forever; if you want to save them, copy them to 
another file first. 
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CHAPTER 



Using RMAKER 



As mentioned in Chapter 9, there are two ways to define windows, menus, cur- 
sors, icons, and other data structures specific to your program. One is to call 
routines such as NewWindow, NewMenu, Appendltem, and so on, embedding 
the information about these items in your program. The other is to create the 
structures as resources, store them in the resource fork of your program code 
file, and then pull them in using the appropriate Toolbox calls. 

The method is more flexible for a number of reasons. First, you specify the 
resources independent of the program itself, so it's easier to make changes to the 
resources without altering the program. Second, in applications such as ResEdit, 
you can edit the resource fork of a program without changing the machine code, 
which means that you can modify the resources without having to recompile the 
program. Third, you can more easily develop international software: You can 
store all text (menus, window titles, strings) as resources and simply have a dif- 
ferent resource file for each language (such as English or Spanish). 

This chapter gives you enough information to get started on using resources. 
Also, Chapter 5 contains detailed information on resources. In addition, check 
the appropriate chapters of Inside Macintosh for the given data types (menus, 
and so on). 



137 



A Quick Guide to Using Resources 



There are five steps to follow to use resources in your programs. They are listed 
here and then explained in the subsequent sections. 

1. Create the resource text file. You can do this with the Turbo Pascal 
editor and save it with a file name ending in .R, such as MYPROG.R. 

2. ''Compile" this resource text file into a resource "code" file by running 
RMAKER. The resulting file can be named just about anything you'd 
like, but the Turbo Pascal convention is to give it the same name as the 
resource text file with the file extension .RSRC, such as MYPROG. 
RSRC. 

3. Make the appropriate changes to your program so that it reads in the 
resources as needed. This chapter gives a list of the most commonly 
used routines. All other routines (for menus, windows, dialogs) are in 
the corresponding sections of Inside Macintosh. 

4. At the beginning of your program, put a {$R (filename)} compiler 
directive to tell the compiler which file the resources are located in. 
For example, if you are working on the file MYPROG. RSRC, then the 
compiler directive would be {$R MYPROG.RSRC}, 

5. Compile your program as usual. When running the program in mem- 
ory, Turbo Pascal automatically opens the resource file before transfer- 
ring control to the program. When it compiles the program to disk, 
Turbo Pascal copies all resources in the resource file into the resulting 
code file. 

That's all there is to it. If you're already familiar with each of those steps, you 
can skim through the rest of this chapter. Otherwise, the following sections dis- 
cuss each step in detail. 

Creating a Resource Text FUe 



The first step is to define your resources in a resource text file. It's almost like 
writing a program; however, instead of defining actions, you define menus, win- 
dows, and other similar items. These are known as resources and can be stored 
for use in a number of places: within a document, an application, the SYSTEM 
file, or in a separate resource file. In all cases, they are placed in what is known 
as the resource fork of that file (as opposed to the data fork, which holds any data 
associated with that file). Your program can then load and use the resources as 
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needed. To get them there, however, you must first specify them in a resource 
text file, then use RMAKER to convert them to the proper resource formats. 

You must abide by certain rules when creating a resource text file. 

• All resource definitions must be separated by blank lines. 

• All resource types must be four characters long. Take particular care when 
defining a resource of type STR ; don't forget to put a blank after the R. 

• Comments are allowed. Any line beginning with an asterisk (*) is ignored. You 
can place comments on the same line as the information by preceding the 
comments with two semicolons (;;); the rest of the line (semicolons included) is 
then ignored. 

• Resource templates are fairly rigid; you can't rearrange them to suit your own 
preferences. 

• Trailing and leading blanks are ignored, except in strings and in separating 
numeric values on the same line. 

• If data (such as a string) can't fit on one line, end the data with two plus signs 
(+4-) and continue on the next line. You can do this for several lines; remem- 
ber, though, that strings are limited to 255 characters. 

• If you want to include resources from the resource forks of other files, just type 
Include <f ilename> such as 

Include MYOTHEEDEMO.RSRC 

Note that these are "compiled" resources, that is, resources that have 
already been converted from text to binary format (by using RMAKER, for 
example). 

• All numbers are in decimal (base 10), unless preceded by the . H directive. In 
that case, they are assumed to be hexadecimal (base 16) for the duration of that 
resource definition, or until an .1 (decimal Integer) or .L (decimal Longint) 
directive is encountered. You will probably use these directives ONLY in a 
GNRL resource. 

• Special characters (ASCII codes less than 32 or greater than 126) can be 
inserted using a backslash, followed by two hexadecimal digits. For example, 
the Apple character has an ASCII code of 20; to use it as, say, a menu title, you 
would enter \14, since 14 in hexadecimal is equal to 20 in decimal. 
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Resource FUe Header 



Every resource text file should start with the output file name. This should be 
the first non-comment, non-blank line of the file. As mentioned, the convention 
is to give the output file the same name as the text file, but ending with .RSRC 
instead of .R. The line following the output file name should either specify the 
file type and file creator, or be blank. For example, the two Unes 

YPROG.RSRC 
APPLDHOl 

tell RMAKER to create the output file M YPROG.RSRC with the file type APPL 
and the file creator DM01. 

The file type and creator bytes are normally left blank in the resource text file. 
To specify the file type and creator of the final application, you should place a 
{$T ttttcccc} compiler directive at the beginning of your program. For example, 

{$T APPLDMDl} 

If you wish to add the resources defined in your resource text file to those in an 
existing resource file, place an exclamation point in front of the output file name. 
For example, 

1HYPR0G.HSRC 

It's a common practice (for applications) to define a dummy string resource, 
whose type is the same as the application's signature (file creator), and whose ID 
is zero. This string, called the version data resource, specifies the program name 
and version, for instance: 

type DMDl = STR ; note: blank space after 'STR' 

/D ; zero ID 

MY PROGRAM, Version l.G, 51 Apr IRfl? 

This forms the start of your resource file. The balance comprises resource 
definitions, which can then be read in by your program. 

Defining Resources 



Each resource or object to be defined has the following basic structure: 

type <resource type> 
<naBe>r<id> (< attributes >) 
<specifications> 
<blank line> 
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Groups of resources of the same type can be defined by repeating the {id), 
(specifications), and (blank Une) sections. Remember, each instance of a resource 
must be separated firom others by blank hues. 

The Macintosh supports over 30 standard resource types; however, only 12 of 
them are recognized by RMAKER: 

ALRT Alert box for error messages, warnings 

BNDL Bundling information (for icons, file types, etc.) 

CNTL Controls scroll bars 

DITL Dialog item — objects in dialog or alert boxes 

DLOG Dialog box — user input, selection 

FREF File reference — linking file types, icons 

GNRL General — for defining other resource types 

MENU Menus — menu title with list of commands 

PROG Procedure — machine code 

STR String — text strings used within the program 

STR# String list — a list of text strings 

WIND Window — window title, size, attributes, type 

Some of the additional types recognized by the Toolbox and OS routines but 
not directly supported by RMAKER include ICON (icon), CURS (cursor), and 
others. To define them, you must use the GNRL type and start the definition 
with 

type <resource type> = GNRL 

The same method is used to define your own resource types. This is discussed 
in fiirther detail at the end of the chapter. 

Each resource may be given a name. It can then be referenced by that name. 
The name can be up to 255 characters long, though youll want to keep it fairly 
short to avoid eating up too much memory or disk space. If you choose not to 
give the resource a name (a common practice), you must still place a comma 
before the resource ID. 

Each resource must have an ID, an integer value that uniquely identifies it 
from all other resources of the same type stored in your program's resource fork. 

• The values from --32768 to —16385 are reserved for system use. 

• The values from -"16384 to —1 are reserved for system resources owned by 
other system resources (the private resources of a desk accessory for example). 

• The values fi*om 0 to 127 are also reserved for system use. 

• You can use any value from 128 to 32767. 
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Note that resources of different types — say, MENU and WIND - — can have 
the same ID, but all resources of a given type (such as MENU) must have differ- 
ent IDs. 

Each resource has a set of attributes associated with it. Each attribute is repre- 
sented by a single bit. To enable that attribute, you must set the bit to one. 
Here's a partial list of those attributes, their bit positions and values, and what 
happens ff the attribute is set: 



Attribute 


Bit 


Val 


Effect on resource of setting bit 


resPreload 


2 


4 


load after opening resource file 


resProtected 


3 


8 


can t be changed by Resource Manager 


resLocked 


4 


16 


can't be relocated or purged 


resPurgeable 


5 


32 


can be purged 


resSysHeap 


6 


64 


load in system heap 



To set one or more of these attributes for a given resource, just add the 
corresponding values together and place the sum (in parentheses) right after the 
resource ID. For example, a resource with the name of MyRes, an ID of 1000, 
and the attributes Preload (4) and Locked (16) would look like this: 

HyReSrlOOO (EQ) 

Setting attributes is optional. If you do not specify any attributes, a value of 0 
(all attributes disabled) is assumed. Also note that you should not try to set any 
other attributes; all other bits are reserved for system use. 



Resource Specifications 



The resource specification depends entirely upon the resource type. The 
predefined types (including those not directly supported by RMAKER) have 
fixed formats; these must be adhered to when defining the resource. It is possi- 
ble, though, to define your own resource and load it from your program. In that 
case, the data structure you use must match the resource as defined in the 
resource text file. 

Following is a list of commonly used resource types, including all those recog- 
nized by RMAKER and some that are not. Each section tells where the resource 
is mentioned in Inside Macintosh, gives a very brief description of what the 
resource does, shows an example of one in a resource file, and states how you 
would load the resource from within your program. In the last case, the variable 
to which the result of a fimction call is being assigned is always assumed to be a 
handle to that resource type. 
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ALRT— Alert template 



Chapters: "The Dialog Manager* (1-13) 

An alert box is a special type of dialog box used to caution, warn, or even stop 
the user; it uses a list of dialog items (see DITL). 

type ALRT 

tlBSi (^) ; preloaded to avoid disk access 

IDD 50 150 E50 ; top left bottom right 

IDDQ ; ID of item list (DITL) 

F7ai ; stages (^th 3rd 2nd 1st) 



BNDL — Bundling information 

Chapters: **The Finder Interface" (III-l) 

A bundle defines an application's signature (the same as its file creator) and the 
resource ID of its version data. It specifies (through a list of FREF resources) all 
file types related to the application and the icons (through a list of ICN resources) 
to be displayed by the FINDER. The local IDs in the list are needed only by the 
FINDER. For a bundle to be processed by the FINDER, set the bundle bit 
when compiling the appUcation: Place a {$B+} directive in the beginning of the 
program. The DM01 signature must have its own resource, such as TYPE 
DMD1«STR rOTEXT. 



type BNDL 

DMOl D 
ICN# 

Q i2fi 1 laq 

FREF 

Q Ida 1 leq 



resource ID 

signature and version data ID 
ICN# map 

local ID 0 is resource ID 15fl; 1 is l^H 
FREF map 

local ID D is resource ID 1E&; 1 is 12R 



CNTL — Control template 

Chapters: "The Control Manager" (I-IO) 

A control is a graphical object on the screen that the user can modify (using the 
mouse) as a form of setting or data input. Controls may be specified as Visible or 
Invisible, 



type CNTL 

,25t (^) ; preloaded 

Throttle ; control title 

IDQ 50 250 tt ; top left bottom right 

Visible ; attribute 

It ; control definition ID (ProcID) 

0 ; reference value (RefCon) 

0 999 0 ; minimum, maxium, initial value 



An example of accessing a control template follows: 
theCntl :« GetNewControl(25fci,theWindow) ; 
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CURS— Cursor 



Chapters: ^'QuickDraw'' (1-6), "Toolbox Utilities" (1-16) 

The cursor is the shape that moves around the screen as you move the mouse. 
Besides the default arrow, there are four standard cursors that you can load, or 
you can define your own. 



type CURS = GNRL 
rl5fl (^) 
.H 

» cursor data 
D7E0 Ifllfl 3DDC bOOt 
<<E5 fl^21 fl^ai flODl 
flDDl Rfiiq flC31 47EE 
tODt 3DDC Ifllfl D7ED 
* cursor mask 
DDDD DOOD DDDD DDDO 
DDDO DDOD DDDD DDDD 
DDDD DDDD DDDD DDDD 
DDDD DDDD DDDD DDDD 
» hot spot 

DDDfl DDDfl ; (y,x) = (fl,fl) 

An example of accessing a cursor resource follows: 
myCurs := GetCursor(15fl) ; 



preloaded 

hexadeciial data follows 
Ibxlb bitmap, top to bottom 



Itxlt bitmap, top to bottom 



DITL — Dialog item list 



Chapters: ''The Dialog Manager" (1-13) 

Specifies the items — texts, buttons, icons — used in dialog and alert boxes. 
Eight different item types are available: StatText, EditText, Button, RadioBut- 
ton, CheckBox, Iconltem, Picltem, and Userltem, Items may be specified as 
Enabled or Disabled; they are assumed to be enabled if you don't specify any- 
thing. All coordinates are relative to the window of the dialog or alert box using 
the items. Be sure to have blank lines between all item specifications. 



type DITL 

,1DDD 

fl 

StatText Disabled 
ED tiD 3^ lUQ 
Print the document 

EditText Enabled 

150 <5 i^D iqs 

Annual Report 

Button 

15 17D 34 55D 
Cancel 



resource ID 

number of items in list 

static text 

top left bottom right 

text 

edit box 

top left bottom right 
initial text 

rounded button 

top left bottom right 

text (in button) 
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RadioButton 

5D 15 t< lAU 

fl 1/E" X 11" paper 



; radio-type button 
; top left bottom right 
; text (to right of button) 



CheckBox 

15 iiD eoQ 

stop after each page 



; check box 

; top left bottom right 

; text (to right of check box) 



Iconltem Disabled 
10 ED 52 
lEA 



; icon 

; top left bottom right 
; ICON resource ID 



Picltem Disabled 
D lOD D 100 
lEfl 



; QuickDraw picture 
; top left bottom right 
; PICT resource ID 



Dserltem 

150 150 EDO EDO 



; user-defined item 
; top left bottom right 



DLOG — Dialog template 

Chapters: "The Dialog Manager* (1-13) 

A dialog box displays information and allows user input or modification. Like 
an alert box, it uses a list of items (DITL) to determine its layout. A dialog may 
be specified as Visible or Invisible, followed by GoAway or NoGoAway to deter- 
mine whether it has a Close box. 



An example of accessing a dialog template is 
theDialog :- GetNewDialog(lDQOrnil,Pointer{-l) ) ; 

FREF — File reference 

Chapters: "The Finder Interface" (III-l) 

Used in conjunction with a bundle resource (BNDL). An FREF associates a 
file type with a local ID used in the bundle. This local ID in turn determines the 
resource ID of the icon (ICN#) to be displayed for files of that type created by 
the application. 

type FREF 

,12fl ; resource ID as found in BNDL 

flPPL 0 ; file type and local ID 



type DLOG 

,1DD0 {A) 

fl Dialog Box 

50 100 300 ^50 

Visible NoGoAvay 

D 

□ 

IDOD 



preloaded 
title 

top left bottom right 
attributes 

window definition ID (ProcID) 
reference value (RefCon) 
item list ID (DITL) 
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DHTX I 



; resource ID as found in BHDL 
; file type and local ID 



ICN — Icon list 



Chapters: '"The Finder Inteface" (3-1) 

An icon followed by a mask, used primarily for associating icons with files in 
the FINDER. 



type ICH 



6NRL 



* icon data 
FFFFPPFF flDDDDDDl 

aaoDDDOi fiooooooi 

BODODDDiPFFFFFFF 

* icon mask 
FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF 



resource ID 
hex values 

aex35 bitnap 



32 longwords in total 
aexBS bitmap 



FFFFFFFF FFFFFFFF 



35 longwords in total 



ICON— Icon 



Chapters: "Toolbox Utilities" (1-16) 

A single icon that can be associated with other resources (such as item lists for 
dialogs) or can be read in by your program. 



type ICON = GNRL 
.H 

FFFFFFFF 7FFFFFFF 
3FFFFFFF IFFFFFFF 

Qoaaoooi'ooDODOol 

.H 

flODDDODO CDQDDODO 
EOODDDOD FOODOOOO 

FFFFFFFE* FFFFFFFF 



resource ID 
hex values 
35x32 bitmap 



3E longwords in total 



resource ID 
hex values 
3Ex3E bitmap 



35 longwords in total 



An example of accessing an icon resource is 
thelcon := GetlconClE'l) ; 
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MBAR — Menu bar 



Chapters: *'The Menu Manager'' (I-ll) 

Defines an entire menu bar through a hst resource IDs for individual menus 
(MENU). 

type NBAR " 6NRL 



rlDDD ; resource ID 

.1 ; integer values 

5 ; number of menus in bar 

IQDQ ; resource ID of 1st menu 

IDDl ; resource ID of End menu 

IDOE ; resource ID of 3rd menu 

EDDD ; resource ID of 4th menu 

aoOl ; resource ID of 5th menu 



An example of accessing a menu bar resource is 
theMBar : = GetNewMBar(5DDD) ; 

MENU— Menu 

Chapters: **The Menu Manager" (I-ll) 

Defines a menu, that is, the menu title that appears on the menu bar and the 
listed commands, including any command-key equivalents. You can, as with 
other resources, list mutiple resources under one type statement. 

type MENU 



rlODD ; 


resource ID 


\IA 


title (Apple character) 


About MyPrograra... 


first command 


(- 


disabled dotted line 


,IUUI ; 


resource ID 


file 


title 


New/N 


New coiiand (QSJ) 


Open/0 


Open command (SEj) 


Save/S 


Save command ((^J^) 


Save As... 


Save As command 


Close 


Close command 


{- 


separator line 


Quit/Q 


Quit command (CsJQJ) 


,1002 


resource ID 


Edit 


title 


Undo/Z 


Undo command ([liCID) 


(- 


separator line 


Cut/X 


Cut command ([pSl) 


Copy/C 


Copy command H^g II C i) 


Paste/V 


Paste command (Igjl VJ^ 


Clear 


; Clear command 


(- 


; separator line 


(Options. . . 


; Options command (disabled) 
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Here's an example of accessing a menu resource: 
theHenu :> GetHenu(lOOD) ; 



PAT— Pattern 

Chapters: '^QuickDraw" (1-6), **Toolbox Utilities' (1-16) 

Represents an 8x8 pattern that is used for drawing and filling. Be sure to 
leave the trailing space after PAT 

type PAT » 6NRL 

,snu ; resource ID 

.H ; hex values 

FFDD FFDQ ; alternating black/white lines 

FFDD FFOO ; total of eight bytes 

Example of accessing a pattern resource: 
thePat := GetPattern(5D0) ; 



PAr=ff=— Pattern list 



Chapters: ^'QuickDraw" (1-6), "Toolbox Utilities" (1-16) 

List of patterns, all under one resource ID. The GetlndPattern procedure lets 
you specify which one (1,2,..,N) you want. 

GNRL 

resource ID 
integer value 
number of patterns 
hex values 
1st pattern 
End pattern 
3rcl pattern 
^th pattern 
5th pattern 



type PftT# 

.1 

5 

.H 

FFDD FFDD FFDD FFDD 
flfi^'^ 2E11 flfl4< EEll 
3FflA RBCq BflDA UU3 
ODDD DlflO DlflD DDDD 
AA55 AA55 AA55 AA55 



Example of accessing a pattern in a pattern list {myPat is a variable of type 
Pattern): 

GetlndPattern ( myPat , ^UU,A); 
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PROC— Procedure 



The PROC type is used to create resources that contain machine code. It reads 
the first code segment from an application file (the CODE resource with ID = 
1), strips the first 4 bytes oflP of it (these are used by the Segment Loader), and 
saves it as a resource of type PROC (unless retyped as shown below). It is mainly 
usefiil for defining other code resource types, such as CDEF, DRVR, FKEY, 
INIT, MDEF, PACK, PDEF, and WDEF. 



type PROC 
MyProcedure 
type CDEF = PROC 
MyControl 



create PROC resource 
; resource ID 
; filename 

; create CDEF resource 
; resource ID 
: filename 



STR— String 

Chapters: "Toolbox Utilities" (M6) 

Represents a text string; note the trailing blank after STR . If you need to 
continue a string onto another line, use the ++ continuation mark. All leading 
and trailing blanks are significant. 

type STR 

flDQO (^) ; resource ID (preloaded) 

Turbo Pascal for the Macintosh 

,1001 (4) ; and another string 

Copyright (C) I'lflt by Borland International 

,1005 (4) ; and another 

All rights reserved. 

Example of accessing a string resource: 
theStr :« GetString(lODl) ; 



STR#— String list 

Chapters: "Toolbox Utilities" (H6) 

Represents a list of strings. Same rules apply as for STR #. 
type STR# 

,lEfl (4) ; resource ID (preloaded) 

3 ; number of strings 

Turbo Pascal for the Macintosh 

Copyright (C) l^flt by Borland International 

All rights reserved. 
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Example of accessing a string in a string list (myStr is a variable of type 
Str25S): 

GetIndString(inyStr, 15fl , a ) ; 



WIND—Wimhw 

Chapters: *The Window Manager" (1-9) 

Defines a window. A window may be specified as Visible or Invisible, followed 
by GoAivay or NoGoAtvay to determine whether it has a Close box. 

type WIND 
,1000 

This Program 
AA 7 335 505 
Visible Goftway 
0 
G 



,1001 

About This Prograi 
qO 50 IflD 

Invisible NoGoAway 

IL 

0 



resource ID 
window title 
top left bottom right 
attributes 

window definition ID (ProcID) 
reference value (RefCon) 

resource ID 
title 

boundaries 
attributes 

window definition ID (ProcID) 
reference value (RefCon) 



An example of accessing a window resource follows: 
theWindow := GetNewWindow(100D,nil,Pointer(-l) ) ; 



Defining Your Own Resources 



You Ve already learned much of what you need to know about defining your own 
resources. Since RMAKER only supports twelve of the standard resource types, 
we've had to define the others in terms of the general resource type, GNRL. But 
what if you want to define a resource that isn't found among any of the standard 
types? Here's what you would do: 

• Define the resource in terms of a Pascal data structure — most likely an array 
or a record. 

• Determine the byte-by-byte mapping of the data structure, that is, the size 
and starting oflset of each element or field. 

• Design a skeleton resource type based on the byte-by-byte mapping, and 
define resources in your file using this skeleton. 

• Read the resources into your program using the GetResource function. 
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Let's look at an example. Suppose you wanted to define a resource type called 
CUBE. Your data structure migjit look something like this: 

type 

Cube ^ record 

vertex: array[l. .6,X. .3] of Integer; 
color: Pattern; 
title: Stress ; 
end; 

CubePtr = '^Cube; 
CubeHndl = ''CubePtr; 

var 

MyCobe: CubeHndl; 

The mapping of the Cube record is as follows: 48 bytes for the vertex hst (2 
bytes each), followed by 8 bytes for the color, followed by between 1 and 256 
bytes for the title (the length is stored in the first byte). A resource based on this 
could be 



type CUBE 

,1000 

.1 



6NRL 



D 


0 


0 


1st vertex 


Q 


D 


100 


End vertex 


0 


100 


0 


3rd vertex 


100 


0 


0 


4th vertex 


0 


100 


100 


Sth vertex 


100 


0 


100 


tth vertex 


100 


100 


0 


7th vertex 


100 


100 


100 


flth vertex 


.H 






hexadecimal 


AAS5 


AA55 


USS AA55 


pattern 


.P 






Pascal strii 


This 


is my 


cube 


title 



resource ID 

decimal integers follov 



Having defined such a cube in your resource file, you could read it into your 
program and process it with the following statements: 

MyCube := CubeHndl(GetResource( 'CUBE' ,1000) ) ; 

with MyCube*'* do 

begin 

{ do whatever you want to > 
end; 

You can use Turbo Pascals retyping mechanism to convert from the generic 
handle that GetResource returns to the specific data type CubeHndl 

If your resource includes a string, it should be the last item in the resource. 
When a string is declared in Pascal, say with a maximum length of 80, the com- 
piler sets aside 81 bytes for that string, even though its dynamic length may be 
less. However, when RMAKER processes a string, it only stores as many charac- 
ters as you write (plus the preceding length byte). 

Now, if the title field in the Cube record was the first field, you would have to 
write exactly 255 characters for the following fields to line up properly; by placing 
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it at the end, you can write a string of any length. Be aware, though, that the 
handle allocated by GetResource only has room for the string you write, not for 
the full 255 characters. 

Here's a list of the data type commands that you can use, with a brief explana- 
tion of each: 

• .H Hexadecimal values follow. RMAKER accepts the values as integers (four 
digits) or long integers (eight digits). 

.H 

OOFDO 1E3< ODFF <3E1 
DDFFFFOO FFODDDFF 

• .1 Decimal integers follow. Values must be in the range —32768 to 32767, 
separated by blanks. 

.1 

3E -532 IUUA3 IS 

• .L Decimal long integers follow. Values must be in the range —2147483648 to 
2147483647, separated by blanks. 

.L 

t<23R3 -lODlDl 0 3 

• .P Pascal string follows. A length is calculated and stored as the first bytes, 
followed by the text itseE Leading blanks are significant. Use the continuation 
symbol to extend to the next line. The maximum length is 255 characters. 

.P 

And still I persist in wondering if folly ++ 
must always be our nemesis. 

• . S String follows. Only the text is stored; no length is calculated. No maximum 
length. 

.S 

Four score and seven years ago, ++ 
our forefathers brought forth upon ++ 
<and so on> 

• .R Resource follows. The next line gives a file name, a resource type, and a 
resource ID; the corresponding resource is copied from the given file. 

.R 

MyStUff MEKO IDDD 



152 



Turbo Pascal for the Macintosh 



Using BMAKER 



RMAKER itself is a very easy application to use. You can open it fix)m the des- 
ktop by double-clicking on it, or you can transfer to it using the Transfer menu 
from within Turbo Pascal. 

Once youVe started it, RMAKER brings up a file selector dialog box as shown 
in Figure 12-1. 

4 File Transfer 



Betource Compiler 



Pa$Demos| 



□ MyDemo.R 

□ MyDR.R 



D Turbo Pascal 

[ M<^<^ ) 
[ Driue H 

[ Open ] 
[ Cancel ] 



F^ure 12-1 The RMAKER File Selector Box 

It lists only those files ending with . R; to choose one click on it, then select the 
Compile button, or double-click on the file name. The file selector then disap- 
pears, and the ''compilation" starts. Tjie left side of the display shows the con- 
tents of the resource text file as it is read in, while the right side shows the size of 
the resulting resource code file. 

You can abort the process at any time by clicking the Stop button in the lower 
left corner of the display. 

When it's done and you want to exit RMAKER, click on the Quit button (same 
as the Stop button) or select the Quit command from the File menu. You may 
process another resource file by selecting the Compile command from the File 
menu. And you can transfer back to Turbo Pascal (or any other program): Select 
the Other... command in the Transfer menu, then select the appropriate pro- 
gram from the file selector that appears. 
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C/sf ng Your Resources 



To let your program use a given resource file, just place the name of the resource 
code file in a {$R} directive at the beginning of your program, such as 

<$R MyProg.Rsrc> 

When you run your program in memory, Turbo Pascal automatically opens the 
resource file. When you compile your program to disk, Turbo Pascal copies all 
resources from the resource file into the final application code file. 

To actually use those resources within your program, you must read each one 
in as desired. Most often, this is done as part of an initialization procedure, 
which reads in the menus, windows, and other resources, setting up the desired 
display. Since you usually refer to these resources by their IDs, you must know 
the ID of each one that you are reading in. 

Again, a common practice is to declare those IDs as constants. For example, 
suppose you had defined five menus, with resource IDs 1001 through 1005, 
respectively. You might then write the following code to read them in: 

const 

nenuID = lOOD; 
menuCount = 5; 
type 

MenuList: ar ray [ 1. . menuCount] of MenuHandle; 

procedure Initialize; 
begin 

for I := 1 to menuCount do 
HenuListCJ] GetNenu(iiienuID'^I) ; 

end; 

GetMenu reads in each of the menus from the resource file, points a handle to 
it, and then returns that handle, which is assigned to an element of MenuList 

Similar techniques are used for other resources, though most other resources 
are assigned to individual handles, rather than to arrays. Again, Inside Macin- 
tosh is the best reference for more details on using resources. 
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CHAPTER 



Using FONT/DA MOVER 



This chapter tells you how to use the FONT/DA MOVER to install the desk 
accessories (DAs) that you write in Turbo Pascal. You can then apply these 
instructions on moving DAs to moving fonts. 

Fonts and DAs normally reside in the SYSTEM file of a Macintosh startup 
disk, but can also be kept in "suitcase" files (files with the suitcase icon) for later 
inclusion in a SYSTEM file. The FONT/DA MOVER utility is used to copy or 
remove fonts and DAs on Mac disks. Apple's FONT/DA MOVER program is 
included on your Turbo Pascal distribution disk. 

Text fonts are used by the system, the Turbo Pascal editor, and your applica- 
tion programs. These fonts are usually provided as part of your Mac computer. 
Using the Macintosh, the handbook that came with your Mac, explains how to 
use FONT/DA MOVER. 



Starting Up FONT/DA MOVER 



There are three ways to start up the FONT/ DA MOVER. First, if you are in 
Turbo Pascal and have included the FONT/DA MOVER in the Transfer menu, 
select that menu option, exit Turbo Pascal, and enter the FONT/DA MOVER. 
When adding the FONT/DA MOVER to the Turbo Pascal Transfer menu, 
remember to rename the file to change the slash (/ ) to another character. (We 
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suggest using the plus sign, +.) You must make this change both to the Transfer 
menu and to the FONT/DA MOVER file itseE 



I ^ File Edit Search format Font Compile 



I SpeaK-Pas ! 




progran Sp«ak; 

{$fl Speak. Rsrc) 
{$fl+> 
{$u-> 
uses 

MemTypes, Qu i ckDraw, OS I ntf , Tool intf , Paiek I ntf , SpMchlntf ; 
type 

Charfirroy = packed array tO. .99991 of Char; 

const 

npplttMenu = 256; 
Pi leMenu « 257; 
Spcaktlenu «* 258; 

Creator > 'OHIO'; { since «»e're going to use Mac file. system calls } 
FileTup« ■ 'OTflV; < directly/ we need to define a these strings } 

var 

errno : integer; 
numChers: Integer; 
Error: SpeeehErr; 
Text In: Chorflrrciy; 
Phonetics: Handle; 



Figure 13-1 The Transfer Menu 

You can also launch the FONT/DA MOVER from within Turbo Pascal by 
selecting the Transfer command from the File menu. This brings up a standard 
file selector window; scroll through until you find the FONT/DA MOVER, click 
on its name, and then click on the Transfer button. 




Figure 13-2 The Transfer Command File Selector Window 



If you are in the FINDER, you can double-click on the FONT/ DA MOVER 
icon or on a suitcase icon. The DA suitcase in the file results from compiling a 
Turbo Pascal desk accessory program to disk. 
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When the FONT/DA MOVER starts up, a dialog box is displayed. 



OFont 

<i) Desk Rccessory 



Mouer 



Clock 

Control Panel 

Drouiers 

MacCiock 

MacDialer 

MacTerm 

Notepad-^ 



System 
on startup 
3752K free 
[ Close n 



[ Help ] 



Quit 



Open.. 



Figure 13-3 FONT/DA MOVER Dialog Box 



You'll notice two things. First, FONT/DA MOVER automatically opens the 
current SYSTEM file or, if you clicked on a DA suitcase icon, the DA file you 
selected. Second, the top of the dialog box has two buttons. If you launched 
FONT/DA MOVER directly by double-clicking on it or transferring to it, the 
Font button is selected. Click on the Desk Accessory button right below it. 
You're now ready to go on. 



ImtaUing Desk Accessories 



To use a desk accessory, you must copy it into your SYSTEM file. At this point, 
either the SYSTEM file or your DA file is open, probably in the left-hand dis- 
play. Both need to be open, so click the Open button under the other empty 
display. A file selector box comes up; scroll through it and open the appropriate 
file. You should now have a list of desk accessories in each display, one for the 
SYSTEM file and one for your DA file (which probably has only one desk acces- 
sory in it). 
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I U3.2 



OFont 

<§> Desk flccessory 



Area Code Lookup 

Calculator^ 

CalendarBook 

Chooser 

Control Panel 

Drawers 

MacDialer 



System 
on Startup 
3085K free 
[ Close 



[ Help 1 



Quit 



Clock 



Clock 
on Turbo Pascal 

47 MK free 
[ Close ] 



Figure 13-4 Selector Box with SYSTEM and DA Files Open 

Now you can copy your DA into the SYSTEM file. Click on the DA file name 
in the display. At this point, the Copy button is enabled, with arrows showing 
the direction in which the file will be copied. It also shows how large the desk 
accessory being copied is. 

To copy it, select the Copy button. The process may take a while, as the 
SYSTEM file is usually quite large and updating it may require some shuffling. 
When it's done, your DA's name appears in the SYSTEM file display. 



OFont 

® Desk flccessory 



Rrea Code Lookup O 
Calculator^ 
CalendarBook 
Chooser 
Control Panel 
Drawers 
MacDialer 



System 
on Startup 
3085K free 
[ Close 



[ «Copy<0 
[ Remoue ] 



8680 bytes 
selected 



[ Help ] 



Quit 



Clock 
on Turbo Pascal 

47I4K free 
[ Close ] 



Figure 13-5 FONT/DA MOVER with DA Selected for Copying 



Close both files by clicking on their respective Close buttons, then exit 
FONT/DA MOVER by clicking on the Quit button. 
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You can copy DAs out of the SYSTEM file into other files (including other 
SYSTEM files). The same technique is used to move DA files into other DA files, 
so you can build libraries of desk accessories. Click the Open button and select 
the files desired, or create a new one. 

You can also remove DAs from files, including SYSTEM files. Select the DA as 
if you were going to copy it, but click on the Remove button instead. The DA is 
deleted fi-om the file. It is lost for good, so if you wish to save it, copy it into 
another file first. 

You can select more than one DA to copy or remove at a time. Click on a 
name, then drag the mouse up or down while holding the button down to select 
other names. Or you can hold 1^1 down, then click on individual names to select 
them. Then copy or remove the whole group with a single operation. 



A Few Warnings 



You need to be careful of a few things when using the FONT/DA MOVER. First, 
be sure that you have enough free space (memory) on the disk to make a copy of 
the desk accessories selected. Under each file display, FONT/ DA MOVER 
shows the amount of free space on the disk. That number must be somewhat 
greater than the size of the desk accessory(ies) being copied. If you cut it too 
close, the copy operation fails. 

Before removing desk accessories, you should have backup copies. Be very 
careful about removing some of the standard DAs (such as Scrapbook and Con- 
trol Panel) that are crucial to using the Macintosh. 
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CHAPTER 



Debugging Your Turbo Pascal Program 



The term "debugging'* comes from the early days of computers, when actual bugs 
(moths and the like) sometimes clogged up the machinery. Nowadays, it means 
correcting errors in a program. 

Youll undoubtedly have bugs to contend with — errors of syntax, semantics, 
and logic within your program — and you'll have to fix them by trial and error. 
However, there are tools and methods to make it less of a trial and to cut down 
on the errors. In this chapter, well look at common errors and at different 
methods of debugging these errors. 



Compiler Errors 



The first type of error is a syntax or compiler error: You forget to declare a 
variable, you pass the wrong number of parameters to a procedure, you assign a 
Real value to an Integer variable. In other words, you are writing Pascal state- 
ments that don't follow the rules of Pascal. Pascal has strict rules, especially 
compared to other languages, so once youVe cleaned up your syntax errors, most 
of your debugging is done. 

Turbo Pascal won't compile your program, that is, generate machine code, 
until all your syntax errors are gone. If Turbo Pascal finds a syntax error while it 
is in the process of compiling your program. Turbo Pascal stops the compilation. 
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goes into your program, locates the error, positions the cursor there, and brings 
up a window at the top of the screen teUing you what the error was. Once you Ve 
corrected it, you can start compiHng again. 



I ^ File Edit Search Format Font BBMP Transfer | 



^ Error 41: Unlcnouin Identifier | 


HelloUtorid.Pas 


program He 1 1 oUor 1 d ; 
begin 

for D := 1 to 10 do 

UriteLn<'Httl ro Uorld' >; 

ReadLn; 
end. 













Figure 14-1 Turbo Pascal Error Box 



You can even check for syntax errors without generating machine code at all, 
by using the Check Syntax command in the Compile menu. This goes through 
the same process as if you were compiling your program; however, no machine 
code is produced, even if there are no errors. 



Run-time Errors 



Another type of error that can occur is a run-time (or semantic) error. This hap- 
pens when you compile a legal program, but then try to do something illegal 
while executing it, such as open a nonexistent file for input or divide an integer 
by 0. When this happens, Turbo Pascal brings up a Macintosh system error box 
that tells you an error has occurred and gives you the choice of restarting the 
system (essentially the same as turning your computer oflF, then on again) or 
resuming to find where in your program the run-time error occurred. 
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Hel lo Uorld 






Hel 
Hel 
Hel 
Hel 
Hel 
Hel 
Hel 
Hel 


^ Sorry, a system error occurred. 
(Restart) (Resume) 


ID = 04 











Figure 14-2 Mac System Error Box 



The second choice, when available, is preferable. Turbo Pascal again takes you 
inside your program, shows you where the error occurred, and tells you what the 
error was. As with a syntax error, you can then correct the error, recompile, and 
run the program again. 

Input/Output Error Checking 



This type of error is covered in Chapter 5 (pages 41-43), but it is briefly 
described here. 

Suppose you run a program that prompted for and read in two integer values. 
Instead of entering integer values, however, you type in a Real value (that is, a 
number with a decimal point). Your program then halts with a Mac system error 
box. 

Turbo Pascal allows you to disable automatic I/O error checking and test for it 
yourself within the program. To turn oflF I/O error checking at some point in your 
program, include the compiler directive {$1-}. This instructs the compiler not to 
produce code that checks for I/O errors (and that brings up the Mac system error 
box when one does occur). 
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Range Checking 



Range checking is also covered in Chapter 5 (pages 43-44). 

Another common class of semantic errors involves out-of-range or out-of- 
bounds values. Examples include assigning too large a value to an integer vari- 
able, or trying to index an array beyond its bounds. If you want it to, Turbo 
Pascal will generate code to check for range errors. It makes your program some- 
what larger and slower, but it can be invaluable in tracking down any range 
errors in your program. 

You turn range checking on using a compiler directive (see Appendix C for 
more on compiler directives). Insert {$R+} at the start of your program. 

You can leave range checking on all the time by placing {$R+} at the start of 
each program you write. Or, you can selectively implement range checking by 
placing the {$R+} directive at the start of the code that needs it, then placing the 
{$R-} directive at the end of the code. 



Invoking Your Own Run-time Errors 



Suppose your program is getting stuck somewhere, or the system error box 
doesn't let you select the Resume option, or (worse yet) the system error box 
never comes up. What if enabling range checking doesn't track down the error? 
How do you find it? 

You can create your own run-time errors if you want, by calling the Mac rou- 
tine SysError. To do so, you must use the units MemTypes, QuickDraw, and 
OSIntf — all of which youll probably use if you're writing a Mac-style applica- 
tion. You then just call SysError with an integer value, such as 

if <sonie condition> then SysError(35) ; 

When SysError is called, a system error box appears, just as it does for regular 
run-time errors. You can then select the Resume button, which, puts you back 
into your program in Turbo Pascal. 

Theoretically, SysError accepts any integer value. In practice, it acts funny 
with negative values or with positive values above 99. The value 32 is a good 
one, since it doesn't conflict with any currently defined system error (see Volume 
II, Chapter 12, of Inside Macintosh). 
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Tracing Errors 



A tried-and-true debugging practice is to insert trace statements within your 
program. A trace statement is usually just a statement that writes something to 
the screen, telling you where you are and listing some current values. Often it's 
set up to execute only if a global boolean variable has been set to True, so that 
you can turn tracing on or oflF. 

Suppose you have a large program in which some variables are being set to 
wrong (but not necessarily illegal) values. The program consists of several proce- 
dures, but you haven't been able to figure out so far which one has been causing 
the problem. You might do something like this for each procedure: 

procedure ThisOne({aiiy parameters}); 
< any declarations > 
begin 
if Trace 

then WriteLn( 'start of ThisOne: A = ',A,' B = ',B); 
{ rest of procedure ThisOne } 
if Trace 

then WriteLn('end of ThisOne: A « ',A,' B = ',B) 
end; { of proc ThisOne } 

This code assumes that Trace is a global variable of type Boolean, and that you 
somehow set it to True or False at the start of the program. It also assumes that A 
and B are parameters to ThisOne or global variables of some sort. 

If Trace is True, then each time ThisOne is called, it writes out the values of A 
and B just after it is called and again just before it returns to where it was called 
from. By putting similar statements in other procedures, you can trace the 
values of A and B and find out where and when they change to the undesired 
values. 

Once the wrong values of A and B come out in a trace statement, you know 
that the changes occurred somewhere before that statement but after the previ- 
ously executed one. You can then start moving those two trace statements closer 
together, or you can insert additional trace statements between the two. By 
doing this, you can eventually pinpoint where the error is happening and take 
appropriate steps. 

Using a Debugger (MACSBUG) 



Sometimes, none of these approaches work. The nature of the problem(s) is such 
that either you can't track down where the errors are, or having located them, 
you can't figure out why they're occurring or what's causing them. It's time to 
call in the heavy artillery: a debugger. 
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A debugger is a program designed to allow you to trace the execution of your 
program step by step, one instruction at a time. There are many varieties of 
debuggers, but most require that you be familiar with assembly-language 
(machine code) instructions and with the architecture (registers, memory map, 
and so on) of your computer's microprocessor. 

Turbo Pascal comes with such a debugger, known as MACSBUG. To use 
MACSBUG, you just copy it into the SYSTEM folder on your boot-up disk. 
Then, when you boot up your Macintosh, MACSBUG will automatically be 
loaded into memory. The statement MACSBUG loaded appears right beneath the 
ffelcoHie to Macintosh greeting that appears when you start your system. 

If it doesn't load, make sure that the file's name is MACSBUG. The operating 
system looks for that name specifically. This means, of course, that you can con- 
trol whether or not it is loaded by renaming the file; a common **don't load this" 
name is MAXBUG. If you want to load or unload MACSBUG, then you have to 
reboot (which you can do by selecting the Shut Down option in the desktop's 
Special menu, or by turning the Mac off, then on again). 

Invoking MACSBUG 



Once MACSBUG is loaded, you have three ways of invoking it, which you typi- 
cally want to do from within your program. First, while your program is running, 
press the Interrupt switch on the left side of your Macintosh, assuming that you 
have such a switch installed. If you do have that switch, note carefully that it 
actually has two buttons, one closer to the front and the other behind it. The one 
in front is the Reset switch, which causes your Macintosh to act as though you 
had turned the power off and then on again: It is a switch of last resort. The 
switch in back is the Interrupt switch. Press that one to get into MACSBUG. 

The second method is automatic: If MACSBUG is installed, then it is invoked 
whenever you have a run- time (system) error. This is true only if the error actu- 
ally occurred (such as a division by zero). If you produce the error yourself with a 
call to SysError, then the system error box appears as it normally does. 

The third means of invoking MACSBUG is to call it directly from within your 
program. Put the following statement somewhere in the declaration portion of 
your program, that is, after the program statement but before start of the main 
body of the program itself: 

procedure MACSBUG; inline $ARFF; 
You can now get into MACSBUG by calling it: 

if <soiDe condition> then MACSBUG; 
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This causes the MACSBUG display to come up, and you can go on from there. 

To help you debug your programs, Turbo Pascal can include the names of your 
procedures and functions in the resulting machine code. It doesn't normally do 
this, because of the extra space required, but it will if you ask it to, using the 
{$D+} compiler directive. Just place the directive at the start of your program: 

{$D + } 

prograi Whatever; 
The information is compiled and saved for MACSBUG's use. 

The MACSBUG Display 



When you invoke MACSBUG, the screen goes blank, and you'll get a display 
hke this: 



DIUO ERR 

027684: 3B40 FEC2486D tlOUE.U D0,$FEC2<fl5> 

PC=00027684 SR>00002004 TI1=00000F7E 
D0=0000000fl 01=00000001 D2»O0OOFFFF 03=00000000 
04=00000000 05=00000000 06=00000000 07=00000000 
flO=00027B44 fll=000EEF76 02=0000 1E00 fl3=000EEFD6 
ft4=00027B44 fl5=000EEFB4 ft6=00OEEE6n fi7=000EEE6fl 



Figure 14-3 The MACSBUG Screen 

Don't be intimidated by the display; it's actually rather easy to understand. 
The first hne indicates what (if any) made MACSBUG come up, such as DIVQ ERR 
(divide-by-zero error) or DSERBRK (called directly from within your program). If 
youVe brought MACSBUG up by pressing the Interrupt switch, then no mes- 
sage is given. 

The second line shows where your program was when MACSBUG was 
invoked. It gives the address in base-16 (hexadecimal), then shows you the 
machine code instruction in disassembled form. This means that it has converted 
the machine code from binary format to something you can read, such as ORI .B 
#$DE, (AD). (You might not find that particularly legible, but it beats trying to 
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interpret 0D1D3202, the machine-code equivalent.) This instruction, by the way, 
is the next to be executed, which is why its address is the same as the contents of 
the program counter (PC). 

The next hne shows the contents of two important registers (special storage 
locations) of the 68000 microprocessor. The PC is where the 68000 keeps the 
address of the next instruction it wants to execute. The Status Register (SR) is 
where the 68000 sets and clears indivdual bits (Os and Is) to keep track of certain 
information. The third value, TM, keeps track of the number of instructions 
executed. 

The final four lines show the contents of the 68000's data and address registers. 
There are eight of each, D0..D7 and AO. .A7. A7 serves a special purpose as the 
stack register. 

If youVe completely lost at this point, don't worry. What you need to do is to 
find a good reference manual on the 68000 processor, so that you can become 
familiar with what all these things mean. There are several available; one you 
might consider is The 68000, 68010, 68020 Pnmer by Stan Kelly-Bootle and Bob 
Fowler, published by Howard W. Sams & Co. 

MACSBUG Commands 



Well assume that you have become reasonably familiar with the 68000 proces- 
sor, at least to the extent that you want to push ahead. We'll also assume that you 
have put MACSBUG onto your boot disk and rebooted, so that it has been 
loaded into memory. Type in the following program: 

{$D*} 

prograi Test; 
var 

I /Sam : Integer; 

procedure MACSBUG; inline $ASFF; 
begin { main body of program Test } 

ffrite{ 'press return to invoke MACSB0G'); 

ReadLn; 

MACSBOG; 

Sum := D; 

for I := 1 to 10 do 

Sura := Sum + I; 
WriteLn('The sum Is '/Sum) 
end. { of prog Test > 

Now, compile and run it. You'll get the prompt Press return to invoke 
MACSBUG. Press RhI . The MACSBUG display has now come up, and you're ready 
to start debugging. 



168 



Turbo Pascal for the Macintosh 



Table 14-1 follows showing all the MACSBUG commands, after which the 
commands are discussed in some detail. 



Table 14-1 Summary of MACSBUG Commands 



G 


continue execution from PC 


EA 


1 1_ ^ !• A.* 

relaunch application 


ES 


relaunch FINDER 


RB 


reboot 


T^l # /IV / lit , \ 

DM <adr) (#bytes) 


display memory 


IL \aar/ \#lines/ 


disassemble memory 


bM \aar; \vl; (v2; (v2; 


change memory 


y J V / lit . V / IV / IV 

F <adr) <#Dytes) (val) (mask) 


find value 


TD 


display all registers 


PC [val] 


display (or change) program counter 


SR [val] 


display (or change) status register 


DO [val] (ditto for D1..D7) 


display (or change) data register 


AO [val] (ditto for AO. .AT) 


display (or change) address register 


S 


single-step executing 


T 


single step; execute traps completely 


MR 


Single step; execute subroutines 


GT (adr) 


execute until PC = (adr) 


ST <adr> 


like GT, but (adr) can be in ROM 


Tin / J \ 

BR (adr) 


set breakpoint 


CL 


1 11 1 1 • • 
clear all breakpoints 


/ 1 1 V / 1 rtV 

CS (adrl) <adr2) 


• 11 
set up checksum area 


CS 


. • 1 1 

test checksum area 


SS (adrl) (adr2) 


interrupt on change to checksum area 


WH (trap) 


1 . , 
locate trap 


WH (adr) 


find trap near (adr) 


Ai \ti/ \tz/ \ai/ \az/ \cii/ \ciZ/ 


log calls to traps in trap range 


AR (tl) (t2) (al) (a2) (dl) (d2) 


log last call to trap in trap range 


AB (tl) (t2) (al) (a2) (dl) (d2) 


break on any call to trap in range 


AS (tl) (t2) (al) (a2) 


break on memory change from trap call 


AX 


clear all trap commands 


HD 


dump heap 


HT 


show heap totals 


HS (tl) (t2) (al) (a2) 


scramble heap on trap call 



The first MACSBUG command you need to learn is for Go, which causes 
your program to continue execution. It restores the Mac's display first, so that it 
appears as though you had never stopped. However, be aware that (Ji means 
**Go from where I am right now." For example, if you Ve changed the PC so that it 
points to some other area of memory, that's where execution starts. Likevdse, if 
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you Ve changed register values or memory locations, the program continues with 
those changed values. 

Press now and watch yourself go back into your program. Once your pro- 
gram is done, run it again and get back into MACSBUG, 

There are similar commands to exit MACSBUG. The rT)fT) command restarts 
your program, so that you'll exit MACSBUG and begin to execute your program 
again. The rEjA) command gets you back to the FINDER (desktop) or to Turbo 
Pascal if you executed your program in memory. The (^1^ command reboots 
the entire system, that is, it acts as if you had turned your Mac oS and then on 
again. 

The next few commands have to do with displaying the contents of your com- 
puter memory. The values stored in memory can be interpreted as either data 
(information to be acted upon) or instructions (what to do with data). Part of a 
program's job is to keep track of which values are which, so that it doesn't try to 
execute data or manipulate instructions (although both those actions can be 
done). 

Similarly, when you display memory, you have to decide if you want to see it as 
data or as instructions. The Dump Memory (COSJ) command shows memory as 
data. Specifically, it gives you a list of 4-digit hexadecimal (base-16) values, each 
value representing a 16-bit word. The format of this command is 

>DM addr #bytes 

The command DM1E3FD flD displays 128 bytes (64 words), starting at location 
1E3F0. Why 128 bytes? Because MACSBUG assumes all values are in hexadeci- 
mal, unless you specifically request otherwise by putting an ampersand (&) in 
front of the number. If you actually want only 80 bytes, you have to put either DM 
1E3FD 5D (since 50 hex equals 80 decimal) or DM 1E3FD AflD (to specify a decimal 
value). 

The command displays the contents of memory in two forms: first as hex 
values, and then at the end of the line as ASCII characters. If you are dumping 
memory that has text in it, you can easily detect and read that text. The com- 
mand displays eight words (16 bytes) on each line. 

For the address, MACSBUG accepts a variety of expressions. You can, of 
course, put an absolute address there, as shown above. You can also use values in 
registers. For example, the command DM PC 3D displays three lines (48 words 
altogether), starting at the address found in the program counter. Likewise, DM 
TEST+3Q1DD displays 10 lines of data, beginning 30 bytes after the start of your 
program TEST, while DM RAD 20 shows data at the address contained in register 
AO. 
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What if the memory you want to examine has instructions instead of data in it? 
Do you have to disassemble (decode) those instructions yourself? No, you can 
use the command, which decodes the instructions for you. The format is a 
httle diflFerent from that of the rDj¥] command: 

>IL addr #lines 

The command IL 1E3F0 5D disassembles and displays 32 (20 is in hex, remem- 
ber?) instructions, starting at location 1E3F0. You don*t have to specify the num- 
ber of lines; the default is 16. For that matter, you don't have to specify the 
starting address, either. MACSBUG keeps track of the memory location you're 
looking at, so that if you just type IL, it disassembles the next 16 instructions, 
and so on. In fact, you can just press EJ, and MAGSBUG executes the CXIXl 
command again. This is also true for {^XMl and several other MACSBUG com- 
mands. As with (^[Ml, you can use registers (PG, AO, and so on) and symbols 
(TEST), along with offsets (+50,-100), to express the address. 

What if you want to change memory? The SM command allows you to set the 
contents of specific memory locations as data. The format is 

SM addr vail val5 val3 vaU... 

This stores the indicated values at the indicated address. The values can be 
bytes, words (2 bytes), or longwords (4 bytes); MAGSBUG stores them appropri- 
ately. If you want to enter instructions instead of data, you have to *hand assem- 
ble" them yourself; MAGSBUG can't convert them from assembly-language 
instructions to machine code for you, though other commercial debuggers (such 
as TMON) can. 

What if you're looking for a given value in memory somewhere, but you don't 
know where it is? You can then use the Find ((3) command. The format is 
>F addr kbytes value mask 

The addr is the address you want to start at, while #bytes indicates how many 
bytes to examine. The value is what you're looking for; as with the (^SJSJ com- 
mand, it can be a byte, a word, or a longword. The mask allows you even more 
precision by specifying which bits in each location being examined to ignore. For 
example, you might search for a particular command, such as {^fJXEl (Load 
Effective Address). That instruction has the bit pattern OlOOxxxlllxxxxxx, where 
the x's represent information about which registers are involved, and so on. You 
might then use the following instruction: 

>F TEST IDD FICD 

With this command, MAGSBUG searches the range from TEST to 
TEST+256 for the IXITIJA) instruction, ignoring all the x bits in the pattern 
shown above. 
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Having looked at memory, you might want to go back and look at the registers 
again. The QtSl command brings up the same display you had when you first 
entered MACSBUG. 

You can also display the contents of a given register by typing its name: PC, 
SR, AO through A7, and DO through D7. If you type a value after its name (such 
as *D3 lOFA**), then that value is stored in that register. 

To debug a program, you not only want to be able to examine and change 
memory, but to execute instructions. The most useful technique is to execute 
one instruction at a time and see what changes with each step. This is known as 
single-stepping or tracing. 

The basic single-step command is If you enter this command, MACSBUG 
executes the next instruction that the program counter (PC) is pointing at, then 
shows you the next instruction and the register contents. You'll note that the 
screen flashes when you do execute this command; that's because MACSBUG 
momentarily switches back to your program's regular screen display. As with 
fPfW^ and CL3I3» you just press each time to repeat the (JJ command. 

There is one potential problem with using the command. What if the 
instruction you execute calls a Toolbox or operating system routine? You then 
have to single-step through that entire routine before you get back to your pro- 
gram. Obviously, this could be very tedious. The answer is to use the (3 com- 
mand. When MACSBUG encounters a call (known as a "trap**) to a Toolbox or 
OS routine, it just executes the routine without single-stepping. It then stops 
when it gets back to your program, so that the routine ends up looking like a 
single instruction. 

A similar case can occur within your own program. What if you're stepping 
through some instructions and come across a call to one of Turbo Pascal's subrou- 
tines, or even one of your own? You may not want to single-step all the way 
through it. The solution is to use (for that instruction only) the rMjTR) command. 
This lets MACSBUG go to that subroutine, execute it, return to where you 
were, and put you back into single-step mode. 

Let's take this one step farther. What if you are stepping through your pro- 
gram and want to quickly get through some code? You can then use the Go Until 
((JJTD command. The syntax is 
>GT addr 

Your program then executes without stopping until the desired address is 
reached, at which point MACSBUG is again invoked. Notice that your program's 
regular display comes up again until MACSBUG is re-invoked. A variation of 
this instruction. Step Until (tiOQ)* allows the address to be in ROM, that is, 
within the Toolbox and OS routines. 
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Let's make things even more complicated. What if there are several points in 
your program where you want to stop and reenter MACSBUG? You can set 
breakpoints, which are (as you might guess) locations in your program at which 
MACSBUG is automatically invoked. (The call to MACSBUG in the sample 
program can be thought of as a type of breakpoint.) To set a breakpoint, type 

>6R addr 

where addr is once again a standard address expression (absolute, register, pro- 
cedure name, with or without oflFset). Once you Ve set breakpoints, you can see 
where they are by pressing (3(51 without an address. To clear a breakpoint, you 
use the CL Addr ((3Q) command to clear an individual breakpoint, or just 
P^*^ss 1213 to clear them all. 

Just as you can have MACSBUG stop or be re-invoked if and when a given 
instruction is executed, you can also have MACSBUG check if any memory 
location within a given range is changed. This is done using a checksum, which is 
simply the sum of all the locations in that range. If the checksum changes, then 
some location has been changed. Be aware, though, that if two locations are 
changed in certain ways — for example, if their values are swapped — the check- 
sum remains the same, and MACSBUG won't be able to detect the modification. 

The command (£12 is for use during single-step debugging. To set things up, 
use this format: 

>CS addrl addrd 

MACSBUG then computes the checksum in the memory locations from addrl 
to addr2 and remembers it. As you trace through your program, you can re- 
check that range by pressing rcJT) . If any locations have been changed (that is, 
the checksum is diflFerent), then MACSBUG prints CHKSOM F; otherwise, it prints 
CHKSUM T. 

The second command, r$7T) . is for use during multiple-step debugging. It 
uses the same syntax, namely: 

>SS addrl addrS 

You can now press 1^, (2(3» [1XD> or whatever you want. The effect of this 
is that a {^Jf^ command is done after every instruction is executed. As you 
might imagine, this makes your program run very, very, very slowly; it should be 
used only in desperate circumstances or if you're really bored. 

As mentioned before, calls to the Macintosh Toolbox and OS routines are 
known as traps. This is because they're implemented using a special 68000 
instruction called a trap. These instructions always have a hex value of $Axxx and 
(theoretically) range from $A000 to $AFFF. In reality, most of the Mac traps 
have values of $AOxx, $Alxx, $A8xx, and $A9xx. You might have noticed that 
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MACSBUG is smart enough to detect those traps with the (^[3 command and 
print out the name of the corresponding routine on the same line. 

First, if you're not sure which trap is which, use the 1^X3 command. It has a 
varied syntax. The command 

>WH trap 

where trap is a trap's name or number, returns the trap s vector, address, and 
name. If you type 

>WH addr 

then MACSBUG looks for the trap nearest to and preceding that address. This 
last version doesn't refer to calls to that trap, but to where the routine itself is 
actually located. 

There are several MACSBUG commands to help you determine what traps 
your program is calling. The most useful one is (^|T|, which has this syntax: 

>AT trapl trapE addrl addrE dDl dDE. 
The parameters are as follow: 



trapl low end of trap range 

trap2 high end of trap range 

addrl low end of address range 

addr2 high end of address range 

DOl low end of DO value 

D02 high end of DO value 



The command checks for a range of traps; Appendix C in Volume 3 of 

Inside Macintosh contains a complete list. If you only want to check for one trap, 
then you can repeat its name for trap2. Note that trapl {= trap2. Also, you can 
use the trap names if you want, instead of the hex values. Trap2 may be left oflF if 
you aren't specifying an address or DO range. 

Addrl and addr2 specify a range in which to check for the trap values. Note 
that addrl {= addr2. These follow the usual address conventions and may be left 
oflF if you aren't specifying a DO value range. Likewise, DOl and D02 specify a 
range of values in the DO register and are optional. 

Suppose you compile and run TEST, get into MACSBUG, then enter the 
command 

>AT SETPORT GETPORT TEST TEST+3DD 

Now press to rerun your program. The screen flashes as MACSBUG reap- 
pears each time a trap in the range is called. When you finally get back into 
MACSBUG, you'll see a display that looks something like this: 

Afl?^ GETPORT PC:DD4132?D fiO:DDDlSB3a DD:DDDDQODD TMrODDODlEB 
Afl73 SETPORT PC: DD413S74 A0:DDDD0F72 DD:DDDDDDDD TMiODDOOlEC 
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The first value is the trap number; the second, the trap name; the third, the 
memory location where the trap was called; the fourth and fifth, the contents of 
registers AO and DO; the sixth, the time (in ticks). 

What if you don't care about all the calls to those traps except for the last one 
before you get back into MACSBUG? Press [^[Uj which has the same syntax. 
When you run your program, there'll be no flashing or other breaking in. 
Instead, when you get back into MACSBUG, press [AJU. MACSBUG then 
gives you the information shown earlier on the last trap call, as well as dumping 
part of the stack. 

What if you want to stop and drop immediately into MACSBUG whenever a 
given trap (or range of traps) is called? Use the command. As with rAjT| 

and (AKU* can specify memory range and DO value range. Now, as soon as 
one of the specified traps is called (within the desired memory range and so on), 
MACSBUG is immediately invoked and stops at that location. 

The (^[^ command works like a trap-oriented version of the [OXI com- 
mand, which checks for changes within a given memory range. Its syntax is 

>AS trapl traps addrl addrS 

However, addrl and addr2 do not refer to where the traps are; instead, they 
refer to the area to be checked for modifications. Each time a trap (located any- 
where) in the range trapl,. trap2 is called, the memory area addrl.. addr2 is 
checked. If the checksum has changed, MACSBUG is invoked, and you get the 
same trap display as with previous commands. 

You can only have one trap command ([aJXI^CDCSjOSjIAI^) active at any 
one time. To clear the existing command, type (^l^. 

There are also a few commands for examining the heap. A discussion of these 
commands and the heap itself is beyond the scope of this chapter, but here are 
the actual commands: 

>HD dumps the heap to the screen 

>HT shows only heap totals 

>HS trapl trapE addrl addiE scrambles heap if traps called 

There are quite a few reference books on debugging Macintosh programs. One 
is How to Write Macintosh Software, written by Scott Knaster and published by 
the Hayden Book Company's Apple Press. It has additional information on 
MACSBUG, TMON, and writing Macintosh programs in general. 
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CHAPTER 



The Turbo Pascal Menu Reference 



This chapter is designed to help you quickly review all the menu commands 
available in Turbo Pascal. You'll first learn how to select menu commands, then 
review all the menus and what each one does. Finally, you'll go through each 
menu in detail. 



Selecting a Menu Command 



Menu commands can be selected two ways. First, you can use the **point-press- 
drag-release" method. Point to the menu by moving the cursor with the mouse. 
Press the mouse button down and hold it down; the menu's commands appear 
below the menu name. Drag the cursor down to the command you want; that 
command now appears as white text on a black bar. Release the mouse button; 
the command blinks a few times, the menu commands disappear, and the com- 
mand is executed. Any menu command can be selected using this method. 

The second approach, available for most commands, is the command-key 
method. The command key, with the (cloverleai^ symbol on it, sits just to the 
left of the space bar on the bottom row of your keyboard. If you pull a menu, 
you'll notice that some commands have a command-key equivalent listed: the 
[£j symbol, followed by some letter or character. You can select those commands 
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by holding down while you type the specified letter or symbol. For example, 
to select the New command firom the File menu, hold down and type the 
letter N. 



The Menu Bar 




Figure 15-1 The Menu Bar 



The menu bar in Figure 15-1 shows you Turbo Pascal's eight menus: 

• Apple — Use this menu to bring up Macintosh desk accessories while working 
in Turbo Pascal. 

• File — Use this menu to open, save, and close programs and other text files 
that you edit with Turbo Pascal. You can also print files, save options, transfer 
to other programs, and exit Turbo Pascal with this menu. 

• Edit — Use this menu to perform editing and formatting commands, and to set 
certain options. 

• Search — Use this menu to search for given strings and, if desired, to replace 
them with others. It also allows you to bring the cursor home and to cycle 
through your editing windows. 

• Format — Use this menu to organize your editing windows (if you have more 
than one open) and to select the font size within a given window. 

• Font — Use this menu to choose the font to be used in each editing window. 

• Compile — Use this menu to compile and run your programs, to get informa- 
tion about a given program, and to set certain options. 
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• Transfer — Use this menu to exit Turbo Pascal by transferring directly to one of 
a specific list of programs; you can edit this list. 

Having reviewed the basic fiinctions of each menu, let's discuss each menu's 
commands in depth. 



The Apple Menu 



File Edit Search Format Font Compile Transfer 



flbout Turbo... 



{ MyFirst.Pas i 



Calculator+ 

CalendarBoolc 

Chooser 

Control Panel 

MacCiock 

MacDiaier 

MocTerm 

Notepad^ 

TalkingMoose 



Figure JS-2 The Apple Menu 



This is a standard menu found in most Mac applications, and it is always the 
first menu on the menu bar. It has two parts: the About Turbo... command and 
the current list of desk accessories. Since that list varies according to your system 
file, the example shown in Figure 15-2 may not match what you see when you 
pull your menu down. 



About Turbo. . . 

You can't select any of the commands in the Apple menu using the All must 
be selected with the mouse. 

The About Turbo. . . command brings up a window in the middle of the screen, 
giving the Turbo Pascal version number and copyright notice. Press I^Hl or click 
the mouse button to make it go away. 
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Desk Accessories 



The desk accessory commands activate the diflFerent desk accessories (DAs). 
Once activated, most DAs continue to run until you get rid of them (usually by 
choking on the Close box in the upper left corner of the DA's window). It's a good 
idea to close any DAs that you are no longer using. 



The File Menu 



I Edit Search Format Font Compile Transfer 



New 


XN 


Open... 


no 




>:f' 


Close 


n. 


Saue 




Saue Rs... 





I MuFirst.Pas I 



Page Setup... 
Print... 



Edit Transfer... 
Saue Defaults 



Transfer... XT 
quit xq 



Figure 15-3 The File Menu 



The File menu is concerned primarily with reading and writing programs (and 
other data) from and to the disk. The commands fall into three major groups: 
accessing files, printing files, and exiting Turbo Pascal. For more details on these 
commands, review Chapter 3. 



NewlzHI^. 

Opens a new (''Untitled'') window. That window becomes the current editing 
window. If eight editing windows (the maximum) are already open, this com- 
mand is disabled. 
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[Edit Search Format Font Compile Transfer 
Untitled 




Turbo Pascal 

[ Prlue ] 

[ Open n 
[ Cancel ] 



3^ El 



Figure 15-4 The Mac File Selector 



Brings up the standard Mac file selector that allows you to select a file for 
editing. Disabled if eight windows are already open. 

Open Selection Q(XJ 

Attempts to open a file whose name matches the currently selected text in the 
current editing window. Primarily used for opening include files. Disabled if no 
text is selected or if eight windows are already open. 

Close {Zl^ 

Closes the current editing window. If the contents of that window have been 
changed since it was last saved to disk, a dialog box lets you choose to save or not 
save your changes before closing, or to cancel the command. Disabled if no 
windows are open. 



Save {^JM 

Saves the contents of the current editing window out to disk. If that window isn't 
associated with a file (that is, it is "Untitled''), it brings up the standard file-name 
selector, allowing you to enter the file name. Disabled if no windows are open. 
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Save as... (no command equivalent) 



Edit Search Format Font Compile Transfer 



HelloUlorld.Pas 



program He I I oUor I d ; 

var 

l,J,K,L : Integer; 
begi n 
for » : = 
uir I te 
= 10, 
= 0; 
J c 
read I n; 
end. 



|cD Turbo Pascal I 



CD PasDemos 
CD PasPrograms 
CD PasUnits 

m.m 



3 Turbo Pas... 

1 ] 
[ Driue~l 



Saue teHt as: 



[ Saue ] 
I [ Cancel ] 



mm 



Figure 15-5 The File-Name Selector 



Brings up the standard file-name selector, whether or not the current editing 
window is associated with a file. Saves the window's contents out to that file and 
associates the window with that file. Disabled if no windows are open. 



Page Setup, , , (no command equivalent) 



Edit Search Format Font Compile Transfer 



ImagelUriter 



Paper: <g) US Letter 

O US Legal 

O Computer Paper 
Orientation Special Effects: QTall Rdjusted 

□ 50 % Reduction 

□ No Gaps Betuieen Pages 



Ofi4 Letter 

O International Fanfoid ( cancel ] 



Figure 15-6 The Page-Setup Dialog Box 



Brings up the standard page-setup dialog box. Any changes made are erased 
when you exit Turbo Pascal. Disabled if no windows are open. 
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Print, . . (no command equivalent) 



HQ File QQ 


Search Format Font Compile Transfer 


1 


debug.pss 


ImagelUriter 


— ^. Y?i? 




Quality: 


O Best ® Faster O Draft 




Page Range: 
Copies: 
Paper Feed: 


® Ril O From: 1 1 To: 1 | 

rrn — — 

LI 1 

<§> Rutomatic O Hand Feed 


[ Cancel ] 


-BTOT 




1 









Figure 15-7 The Printing Dialog Box 
Brings up the standard printing dialog box. Disabled if no windows are open. 

Edit Transfer.., (no command equivalent) 



I Edit Search Format Font Compile Transfer 



program Ca 1 1 Debugger ; 
{D+> 

uses MemTgpes, Qu i ckDrcw , OS I n t f ; 
procedure GoDabuggar; inlfna SRBFF; 

begin 

UritelrtCHel lo Uorld'); 
CoDebugger; 
SysError<88>; 
wr i te I n<' Goodbye" >; 
read I n 
end . 



Transfer Menu Items: 



RMaker 
UnltMouer 
Font+DR Mouer 
MDS 2:HSM 
ResEdit 



OK ) 



( Cancel ] 



Figure 15-8 The Edit Transfer Dialog Box 

Allows you to edit the list of programs found in the Transfer menu. (Not to be 
confused with the Transfer command in this menu; see next page.) 
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Save Defaults (no command equivalent) 



Saves to disk any changes made using the Options commands in the Edit and 
Compile menus. Otherwise, any changes made are erased once you exit Turbo 
Pascal. 



Transfer r^nTfl 



I Edit J^'»a*''"^ rr>.-mat Tgnt Qnmpilg Tr-gnc-fa|' 



] PasPrograms 



O Screen Programs 
<3i Turbo 
CD Turtle Folder 



rrransfer ] 
h; [ Cancel ] 



Figure JS-9 The Transfer File Selector 



Closes all open editing windows, allowing you to verify whether changes 
made to each should be saved. Brings up the standard file selector, but only lists 
applications (executable programs). If you select one, it exits Turbo Pascal and 
executes that program without going back to the desktop first. 



Closes all open editing windows, allowing you to verify whether changes made to 
each should be saved. Exits back to the desktop. 
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The Edit Menu 



I ^ FHe^^^J Search Format Font Compile Transfer 



program 


Undo 
Cut 






O 


( Clock 


Copy 


nc 


\, June 1986 } 




{$D past 

{$u-> 


Paste 
Clear 


nu 






uses Hci 


Shill L>>rt 




itf,Tool Intf; 




const 


Shin m0ii 


m 


ig to enable desk accesory } 

ig to tell OS that we need time ) 




dCtlEr 
dNecd 




Options... 




typ« 

( The OnOlobals record uii it be pointed to by a handle 
in the dCtI Entry passed in by the operating sgstent. 
This is the only way to htave global variables In a 
desk oeeessory. } 




Dnoiebais - record 
theTlne: DateTlMRee; 

timehtap: packed array [0.. 151 of Byte; 
patUhite: Pattern; 


■ 










K>C] 



Figure 15-10 The Edit Menu 



The Edit menu contains editing and formatting commands. The commands 
are discussed in greater detail in Chapter 3. 



Attempts to undo the last editing command or action you performed. You can 
undo the last undo performed, that is, restore the window contents to what they 
were before you did the first undo command. Disabled when not applicable. 



Cuts the currently selected text, deleting it from the editing window and saving 
it onto the Clipboard (a temporary storage area). Disabled when no text is 
selected. 



Copy 

Copies the currently selected text onto the Clipboard, but does not delete it from 
the editing window. Disabled when no text is selected. 
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Paste {^Jy} 



Copies the contents of the Clipboard into the current editing window at the 
cursor's location. If text in the window has been selected, replaces that text with 
the Clipboard's contents. Disabled if the Clipboard is empty and no window is 
open. 

Clear (no command equivalent) 

Deletes the currently selected text from the editing window without saving it to 
the Clipboard. Disabled when no text is selected. 

Shift Left {^}[Tj 

Shifts the currently selected text one space to the left. Ignored if any part of the 
selected text is already at the left margin of the editing window. Disabled when 
no text is selected and when the selection starts or ends with a partial line. 

Shift Right 

Shifts the currently selected text one space to the right. Disabled when no text is 
selected and when the selection starts or ends with a partial line. 

Options (no command equivalent) 



Search Format Font Compile Transfer 



HelloUJorld.Pas 


Clock.Pas 


program Cloc 

{ Clock Desk 

{$D pasdeska 
{$U-) 

uses llemTtpa 


Toh ...iritk. liHl Sfluto Indent 
Tabuiidth. g, startup Wlndoui 

[ OK ] ( Cancel ] 




O 


const 








dot 1 Enable 
dNeedTIm* 


= $0400; { flag to enable desk accesorg } 

- $2000; { flag to tell OS that we need time } 






type 

< The DRGIobals racord wilt btt pointed to by a handle 
in the dCil Entry passed in bg the operating system. 
This is the only way to have global variables In a 

desk accessory. ) 




1 


DRCIobals - record 
theTlme: DateTimeRec; 















Figure 15-11 The Options Dialog Box 



186 



Turbo Pascal for the Macintosh 



Allows you to set the tabulator width and to enable or disable the auto-indent 
and Startup Window options. The tabulator width must be between 1 and 8. 
When auto-indent is enabled, each new line (created by pressing 1^*^^ is auto- 
matically indented the same number of spaces as the line above. When Startup 
Window is enabled, Turbo Pascal automatically creates an ^'Untitled" window 
when started. The changes only aflFect the current session unless you use the 
Save Defaults command in the File menu to save them as the new defaults. 

The Search Menu 





ik File Edit 


PMBB Format Font Compile Transfer | 






Find... 9€F 


loon.Pas ^^^^^^^^^^^^^^^^^m 




program graft* 

{$U turtle) 
uses mem types, 

const 

min-length « 


Change... XH 




o 




Home Cursor StH 


>tintf, SRNE, turtle; 






Ulindoui 9eiU 








war 

dummy : eventrecord; 
X, y : integer; 








procedure plot<dist : real; angle : 

war 

d : integer; 
begin 

d := trunc<dist>; 

sethead i ng<ang 1 e >; 

forwdCd) 
end; 


integer); 






procedure dragon<dist : real; angle, 
begin 


sign : integer); 






on 









Figure 15-12 The Search Menu 



The Search menu allows you to search for strings (and, if desired, replace 
them), to move the cursor home, and to select the current editing window. 
These commands are discussed in more detail in Chapter 3. 
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Find... i^XD 



I # File tdit B^^JTorinat Font Compile Transfer | 



FindLUhat: {dNeedTime | 
[ OK ] □ Words Only □ Case Sensltlue ( Cancel ] 


{$D ppsdeskace) 

{$u-> 

uses MemTupes, QuickDraw, OS Intf, Tool Intf; 

const 

dCtI Enable = $0400; ( ftag to enable desk accesory > 
dNeedTime » $2000; ( flag to tell OS that uie need time > 

type 

( The OAGIobals record wi 1 1 be pointed to by a handle 
in the dCtI Entry passed in by the operating systen. 
This is the only way to haue global variables in a 
desk accessory. } 

OflGlobals « record 
theTime: DateTimeRec; 


o 


<?\ i:-!'.' 





Figure 15-13 The Find Dialog Box 



Presents a dialog box that lets you enter the string to find and to select options 
for Words Only and Case Sensitive. The default search string is the currently 
selected text (if any). The search starts from the current location of the cursor. 
Disabled if no windows are open. 

Find Next 

Attempts to locate the next occurrence of the search string entered via the Find 
or Change command, starting at the current location of the cursor. Disabled if no 
windows are open or if no search string has been entered. 



188 



Turbo Pascal for the Macintosh 



Change... 



I ^ File tdit l-ormat Font Compile Transfer 



Find What: 
Change To: 






readin 




ReadLn 


( OK ] □tUordsOnly □ Case Sensitiue [Cancel] 




;, 

> 







Figure 15-14 The Change Dialog Box 



Presents a dialog hm that lets you enter both the string to find and the string 
with which to replace it, and to select options for Words Only and Case Sensi- 
tive. 



# File Edit 



Format Font Compile Transfer 




Change? [ Ves 



fill ] ( Cancel ] 



1 to 10 do 

writelnCHeHo Uorld'}; 
= 10; 
= 0; 

= J diu K; 



1^ 



Figure 15-15 The Verification Box 



Each replacement is verified, with Yes, No, All, and Cancel options. Com- 
mand-key equivalents are 1^, 1^, and i^. Disabled if no windows are 
open. 
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Home Cursor 



Moves cursor to the top of the currently active editing window and displays that 
portion of the vdndow. Disabled if no windows are open. 

Window {zJ^ 

Cycles through all opened editing windows, making each successive one the 
current editing window each time this command is selected. Disabled when no 
windows are open. 



The Format Menu 




program graftest; 



{$U turtle) 
uses mem types, quickdrat 

const 

i»in_length = 5; 
root_2 = 1.414; 



ev«itrecord; 
integer; 



Stack Windoius 
Tile Windows 
Zoom Ulindoiu 



point 
10 point 
12 point 
14 point 
1 8 point 
24 point 



SANE, turtle; 



procedure plot<dist : 
vor 

d : integer; 
begin 

. d := trunc<dist>; 

sethead i ng<ang I e >; 

forwd<d> 
end; 

procedure dragonCdist 
begin 



real; angle : Integer); 



real; angle, sign 



Figure 15-16 The Format Menu 



The Format menu has two major functions: to organize windows and to select 
text size. Its commands are discussed in Chapter 3. None of the commands in 
this menu have any command-key equivalents. 



Stack Windows 

Organizes the editing vdndows into a stack, that is, with the current editing 
window in the front and all other windows stacked behind it with only their title 
bars showing. Disabled when no windows are open. 
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Tile Windows 

Organizes the editing windows into tiles, that is, shrinks the windows so that all 
can fit onto the screen at the same time. Disabled when no windows are open. 

Zoom Window 

Expands the current editing window so that it takes up most of the screen. If the 
current window is already at full size, shrinks it back down. Corresponds to 
double-clicking on the window's title bar. Best used with the Tile Windows com- 
mand. Disabled when no windows are open. 

Character Sizes 

9, 10, 12, 14, 18, and 24 points 

Selects the character size to use in the current editing window. If no windows 
are open, selects the default character size for new windows. Each window may 
have its own font size. 

The Font Menu 



I <fc File Edit Search Format Lomniie Transfer 



program ^raftest; 
{$U iurtW 

uses memtypesj quickdraw, «siMf, ioolintf, 

const 
min Jength = 5; 
root_2 =1.414; 

var 

dummy : eventrecord; 
x,y : integer; 

procedure p1ot(dist : real; angle : integer); 
var 

d t integer; 
begin 

d := trunc(disO; 

setheading(angte); 

forvd(d) 
end; 


Courier 
Heluetica 
Toronto 
Chicago 
v^Geneua 
New Voric 
Monaco 




O 

it, 

if 

Q 




Pi 



Figure 15-17 A Typical Font Menu 



The Font menu allows you to select the character font for the text in the 
current editing window. If no windows are open, you may select the default 
character font for new windows. The list of fonts available depends upon your 
system file; Figure 15-17 shows a typical Font menu. . Each window may have its 
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own font type, that is, not all windows have to use the same font. These com- 
mands are never disabled, and none of the commands have command-key equiv- 
alents. 



The Compile Menu 



^ File Edit Search Format Font I 



I Transfer 



m MySecoi 



Run 




To Memory 




To Disic 




Check SyntaH 


xv 


fimi Sri or 




Get Info 




Options... 



MgSccond; 
uses h«mTgp«s, QuickDraw; 



var 

X,V, Radius 
TRect 



: Integer; 
: Rect; 



begin 

Mrite< Enter X: 

ReodLn<X>; 
Urlte< 'Enter V: 
ReadLn<V>; 
UrIteC'Enter radius 
ReadLn(RadiU5>; 

SetRecKTRect, X-Rod i us, V-Rad i us, X+Radi us, V-fRod i us >; 
PaintOvaKTRect); 
ReadLn; 
and. <of progroM MySecond} 



Figure 15-18 The Compile Menu 



The Compile menu allows you to compile and execute your Turbo Pascal 
programs. The Compile menu commands are discussed in more detail in Chap- 
ter 4. 



Executes the program in the current editing window. If needed, compiles the 
program (to memory) first. Disabled when no windows are open. 



To Memory Q^Mj 

Compiles to memory the program in the current editing window. The code file is 
disposed of if you in any way edit the text or exit Turbo Pascal. Disabled when no 
windows are open. 
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To Disk {ziH 



Compiles to disk the program in the current editing window. The code file is 
saved as a clickable application. Disabled when no windows are open. 

Chech Syntax {^ill 

Compiles the program in the current editing window without producing 68000 
machine code; checks for any syntax errors. Disabled if no windows are open. 

Find Error 

Positions the cursor at the statement that caused the last run-time error or, if 
that statement can t be found, at the beginning of the text. Disabled if no error 
has occurred or no windows are open. 



Get Info (^XD 



I # File Edit Search Format Font| 



program Ctock; 



TeKt: Clock.Pas, 5826 bytes, 236 lines. 
Code: 8856 bytes code, 206 bytes data. 

Heap: 871 K bytes in total, 729K bytes free. 



dNeedTime - $2000; < flag to tall OS that we need time } 
type 

{ The DflGlobals record will be pointed to by a handle 
in the dCti Entry passed in by the operating system. 
This is the only way to have global variables in a 
desk accessory. } 

DflGlobals = record 
thelime: DateTirneRec; 
timeflap: packed array tO.. 151 of Byte; 
patUhite: Pattern; 



I [ K' •'j'M.g;;?; ii. !■'■', jij.:r . I K! n . ■ ; 1 1 1 " i ' ;■! : m i ! i ! i i 1 1 " ' ■■; : 1 1 : * in ;i: hp i 



Figure 15-19 The Get Info Box 



Displays information about the program in the current editing window: text 
size, number of lines, code size, and data size. Disabled if no windows are open. 
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Options. . . (no command equivalent) 



^ File Edit Seorch Format Font I 



I Transfer 



<$D p< 



us«s f 
const 



Th 
de: 



Symbol table K-Bytes |32 | gl Ruto Saue Te»t 
Default Directories: 



$U Turbo PascahPasUnits: 



$1 



$R 
$L 



$0 



Turbo Pascal:! nclude Files: 



[ Cancel ] 



thcTiMc: Dat*Ti»^«c; 

timetlqp: packed arragt0..15] of Bgt«; 

patUhiU: Pattern; 



am 







Figure 15-20 The Compile/Options Dialog Box 



Brings up the compiler options dialog box. Allows you to enable or disable the 
auto-save option, set symbol table size, and specify default directories for the 
$U, $1, $R, $L, and $0 compiler directives. 



The Transfer Menu 



I 4 File Edit Search Format Font Compile 



^^^^^^^^^^^HWfffBWB MySecond.Pas ^ 

progran MySecond; 


RMaicer 
UnitMouer 
Font+DR Mouer 






uses neiiiTypes,QuickDrau; 








war 

X, V.Radius : Integer; 
TRect : Rect; 








begin 

Urile< 'Enter X: ' ); 
ReadLn<X>; 

Urite< 'Enter V: •>; 
ReadLn<V>; 

Urite< 'Enter radius: ' ); 
ReadLn<Radius>; 

Se tRec t (TRec t , X-Rad i us , V-Rad i us , X-i-Rad i us, V-f Rod i us 
Pa intOual (TRect >; 
ReadLn; 
end. {of progrom MySecond} 


>; 










P 


9] 



Figure 15-21 The Transfer Menu Default Setup 



The Transfer menu contains a list of applications to which you can directly 
transfer without having to go to the FINDER. Figure 15-21 shows the default 
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setup for the Transfer menu: RMAKER, UNITMOVER, and FONT/DA 
MOVER. The last apphcation is normally called FONT/DA MOVER, but the 
slash has a special meaning within a menu item, and so the name here, as well as 
the actual file name on the disk, must be changed to accommodate that. 

You can edit the list of applications by selecting the Edit Transfer command in 
the File menu. This brings up a dialog box with the current Transfer Menu list; 
you then modify the list using standard editing methods. 



Edit Search Format Font Compile Transfer 



UntI 



Clocic 



{$u-> 

uses hcmTypes,QuicKOraw,OSIntf,Tool Intf; 
const 

dCtlEnobl* - $0400; < flag to enable 
dHeedTime * $2000; < flag to tel I OS 

type 

{ thee DRGIobats record will be pointed 
in tKc dCtlEntry passed in by the opei 
This is the only woy to have global 
desk accassory. } 

DAGIobals • record 

theTime: DateTineRee; 

tlntetlcip: packed arraylO. . 151 of Byte 

potUhite: Pattern; 

potBlack: Pattern; 
end; 



Transfer Menu Items: 



RMoker 
UnitMouer 
Font+DR Mover 

(- 

nsM<o 

GoofyUlriter/G 



OK ) 



Figure 15-22 Transfer Menu Dialog Box 



When you edit the Transfer menu, a number of meta-characters are available: 

Separates multiple items on a single line. 
7** Item has a command-key equivalent. 
Item has a special character style. 
Item is disabled. 

A slash (/ ) followed by a character associates that character with the applica- 
tion, allowing the application to be invoked from the keyboard with that com- 
mand key. Remember to specify the character in uppercase if it*s a letter, and 
not to specify other shifted characters or numbers, A less-than symbol {{) fol- 
lowed by a character specifies a special character style for the item. Five stylistic 
variations are available: B (bold), I (italic), U (underline), O (outline), and S 
(shadow). The text 

GoofyWriter>B/G 

defines an application called GoofyWriter, which is displayed in boldface and can 
be invoked by IgyQ . For a dividing line between the applications, use (-, which 
specifies a disabled dotted line. 
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Once you are done and have saved the Hst, the Transfer menu displays the new 
hst of applications. Take care, however, that any name you add to the list is that 
of an actual application. If it isn't, selecting it will cause an error box to appear at 
the top of the screen with a File not found message. If you define any new 
command-key equivalents, make sure they don t conflict with command keys 
Turbo Pascal has already defined. Also, remember that any changes you make to 
the Transfer menu will be lost when you exit Turbo Pascal unless you select the 
Save Defaults command after making those changes. 
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Tokens and Constants 



Tokens are the smallest meaningful units of text in a Pascal program, and they are 
categorized as special symbols, identifiers, labels, numbers, and character 
strings. 

A Pascal program is made up of tokens and separators, where a separator is 
either a blank or a comment. Two adjacent tokens must be separated by one or 
more separators if each token is a reserved word, an identifer, a label, or a num- 
ber. 

Separators cannot be part of tokens, except in character strings. 

Special Symbols and Reserved Words 



Turbo Pascal uses the following subsets of the ASCII character set: 

• Letters — ^the English alphabet, A through Z and a through z. 

• Digits — ^the Arabic numerals 0 through 9. 

• Hex digits — the Arabic numerals 0 through 9, the letters A through F, and the 
letters a through £ 

• Blanks — ^the space character (ASCII 32), and all ASCII control characters 
(ASCII 0 to 31), including the end-of-line or return character (ASCII 13). 
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digit 






digit 














'■ — 





Special symbols and reserved words are symbols that have one or more fixed 
meanings. These single characters are special symbols: 

+ -»/ = <>[].,():;*©{}$# 

These character pairs are also special symbols: 

<> <« := (* *) (. .) 

Some special symbols are also operators. A single bracket, [, is equivalent to 
the character pair (.; similarly, ] is equivalent to the character pair .)• 

Following are Turbo Pascal's reserved words: 



and 


else 


inline 


procedure 


type 


array 


external 


interface 


program 


unit 


begin 


file 


label 


record 


until 


case 


for 


mod 


repeat 


uses 


const 


forward 


nil 


set 


var 


div 


fimction 


not 


shl 


while 


do 


goto 


of 


shr 


with 


downto 


if 


or 


string 


xor 


implementation 


otherwise 


then 






in 


packed 


to 







Reserved words appear in lowercase boldface throughout this manual. Turbo 
Pascal isn't case sensitive, however, so you can use either uppercase or lowercase 
letters in your programs. 
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Identifiers 



Identifiers denote constants, types, variables, procedures, functions, units, pro- 
grams, and fields in records. An identifier can be of any length, but only the first 
63 characters are significant. 

label identifier, 
constant identifier, 
type identifier, 
field identifier, 
variable identifier, 
procedure identifier, 
function identifier, 
program identifier, 
unit identifier 



letter 



letter 



digit 



underscore 



underscore 




An identifier must begin with a letter and may not contain spaces. Letters, 
digits, and underscore characters (ASCII $5F) are allowed after the first charac- 
ter. Like reserved words, identifiers are not case-sensitive. 

Here are some Turbo Pascal standard identifiers: 

CkarEOL 
GotoXY 

Exit 

StringTOReal 
WriteLn 

In this manual, standard identifiers are italicized when they are referred to in 
text. 
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Labels 



A label is a digit sequence whose value ranges from 0 to 9999. Leading zeros are 
not significant. Labels are used with goto statements. 



As an extension to Standard Pascal, Turbo Pascal also allows identifiers to 
function as labels. 



Numbers 



Ordinary decimal notation is used for numbers that are constants of the data 
types Integer, Longint, Real, Single, Double, Extended, and Comp. A hexadeci- 
mal integer constant uses $ as a prefix. Engineering notation (E or e followed by 
an exponent) is read as "times ten to the power of " in real-types. For example, 
7E-2 means 7 X 10"'; 12.25e+6 or 12.25e6 both mean 12.25 x 10^^ Syntax 
diagrams for writing numbers follow. 



label 



digit sequence ^ ^ 



identifier 



hex digit sequence 



TT — ^ hex digit 



digit sequence 



■T — ^ digit 
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unsigned integer 



digit sequence 



hex digit sequence 



sign 



unsigned 
real — 



digit sequence T^^^^^^~^ ^'9'^ sequence 



scale factor — 



scale factor 



U0-1 ui 



sign 



digit sequence 



unsigned number 



unsigned integer — y 



^ unsigned real 



signed number 





unsigned number 












^ 




sign 


] 







Numbers with decimals or exponents are stored as type Extended (unless 
explicitly assigned to a variable of another real- type). Other decimal numbers are 
stored as type Integer or Longint as needed for that value. 
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A one-to-four digit hexadecimal constant is stored as an Integer (2 bytes). A 
five-to-eight digit constant is stored as a Longint (4 bytes). An integral hexadeci- 
mal value with over eight significant digits produces an overflow error. The 
resulting value's sign is implied by the hexadecimal notation. 

Character Strings 



A character string is a sequence of zero or more characters from the Macintosh 
character set (Appendix E) written on one line in the program and enclosed by 
apostrophes. A character string with nothing between the apostrophes is a null 
string. Two sequential apostrophes in a character string denote a single charac- 
ter, an apostrophe. The length attribute of a character string is the actual number 
of characters within the apostrophes. 

As an extension to Standard Pascal, Turbo Pascal allows control characters to 
be embedded in character strings. The # character followed by an unsigned 
integer constant in the range 0 to 255 denotes a character of the corresponding 
ASCII value. There must be no separators between the # character and the 
integer constant. Likewise, if several control characters are part of a character 
string, there must be no separators between them. 



A character string of length zero (the null string) is compatible only with 
string-types. A character string of length one is compatible with any char-type 
and any string-type. A character string of length n, where n is greater than or 
equal to 2, is compatible with any string-type and with packed-string-types of n 
characters. 

These are examples of character strings: 

'TURBO' 'You"ll see' "" ';' 

#13#10 'Line l'#13'LineE' #7#7'Wake up!'#?#? 
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character string 




string character 




Constant Declarations 



A constant declaration declares an identifier to denote a constant within the 
block that contains the declaration. A constant identifier may not be included in 
its own declaration. 



constant declaration 



identifier 



constant 



sign 1-^ 



constant Identifier 



signed number 



character string 



A constant identifier following a sign must denote a value of type Integer, 
Longint, Real, Double, Extended, or Comp, Real-type constants are stored in 
Extended precision. 



Comments 



The constructs 

{ any text not containing right-brace } 
(* any text not containing star-right-paren *) 

are comments. The compiler ignores them. 

A comment that contains $ immediately after the opening { or ( * is a compiler 
directive. A mnemonic of the compiler command follows the ^ character. The 
compiler directives are summarized in Appendix C. 



Program Lines 



Turbo Pascal program lines have a maximum length of 128 characters. 
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P T E R 17 

Blocks, Locality, and Scope 



A block is made up of declarations, which are written and combined in any order, 
and statements. Each block is part of a procedure declaration, a function declara- 
tion, or a program or unit. All identifiers and labels declared in the declaration 
part are local to the block. 



205 



Syntax 



The overall syntax of any block follows this format: 



block 



declaration part 



statement part 



declaration part 



label declaration part 



constant declaration part 



type declaration part 



variable declaration part 



procedure and function declaration part 



The label declaration part is where all labels that mark statements in the 
corresponding statement part are declared. Each label must mark only one state- 
ment. 



label declaration part 



label 




The digit sequence used for a label must be in the range 0 to 9,999. 

The constant declaration part consists of all constant declarations local to the 
block. 



constant declaration part 



■c 



const 



constant declaration 



The type declaration part includes all type declarations local to the block, 
type declaration part 



The variable declaration part is composed of all variable declarations local to 
the block. 
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variable declaration part 




The procedure and function declaration part comprises all procedure and 
function declarations local to the block. 



procedure and function declaration part 



procedure declaration 



function declaration 



The statement part defines the statements or algorithmic actions to be exe- 
cuted by the block when an activation occurs. 



statement part 



compound statement 



Rules of Scope 



The presence of an identifier or label in a declaration defines the identifier or 
label. Each time that the identifier or label occurs subsequently, it must be 
within the scope of this declaration. The scope of an identifier or label basically 
encompasses its declaration to the end of the current block, including all blocks 
enclosed by the current block. Exceptions follow. 



Redeclaration in an Enclosed Block 



Suppose that Exterior is a block that encloses another block. Interior. Any iden- 
tifier declared in Exterior with a further declaration in Interior excludes Interior 
and all its blocks firom Exterior's scope of declaration. 



Position of Declaration Within Its Block 



Identifiers and labels cannot be used until after they are declared. An identifier 
or labefs declaration must come before any occurrence of that identifier or label 
in the program text, with one exception. 
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The base type of a pointer type can be an identifier that has not yet been 
declared. However, the identifier must eventually be declared in the same type 
declaration part that the pointer type occurs in. 

Redeclaration Within a Block 



An identifier or label can only be declared once in the outer level of a given block 
except if it is declared within a contained block or is in a record's field-list. 

A record field identifier is declared within a record type and is significant only 
in combination with a reference to a variable of that record type. So, you can 
redeclare a field identifier (with the same spelling) within the same block, but 
not at the same level within the same record type. However, an identifier that 
has been declared can be redeclared as a field identifier in the same block. 



Identifiers of Standard Objects 



Turbo Pascal equips you with a set of predefined constants, types, procedures, 
and functions whose identifiers function as if they were declared in a block 
enclosing the whole program. Their scope is the entire program. 

Scope of Interface Identifiers 



Programs or interface-parts containing uses clauses are provided the identifiers 
belonging to the units in the uses clauses. These identifiers act as if they were 
declared in a block enclosing the whole program. 
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Types 



When you declare a variable, you must state its type, A variable's type circum- 
scribes the set of values that it can have and the operations that can be per- 
formed upon it. A type declaration specifies the identifier that denotes a type. 



type declaration 



type 



simple type 



pointer type 



structured type 



string type 



type identifier 



When an identifier occurs on the left side of a type declaration, it is declared 
as a type identifier for the block in which the type declaration occurs. A type 
identifier s scope does not include itself, except for pointer types. 
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The following list of terms distinguish the seven types of identifiers according 
to what they denote: 

• simple-type 

• structured-type 

• pointer-type 

• ordinal-type 

• integer-type 

• real-type 

• string-type 

A simple-type identifier, for example, is declared to denote a simple-type vari- 
able, and so on. 

Simple'Types 



Simple-types define ordered sets of values. 



An integer-type identifier is one of the standard identifiers Integer or 
Longlnt. A real- type identifier is one of the standard identifiers: Real, Single , 
Double, Extended, or Comp. See **Numbers* and ''Character Strings" in Chapter 
16 for how to denote constant integer-type and real-type values. 



Ordinal-Types 



Ordinal-types are a subset of simple-types. All simple-types other than real- 
types are ordinal-types, which are set oflFby the following four characteristics. 



simple type 



ordinal type 



^ real type 



real type 
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All possible values of a given ordinal-type are an ordered set, and each possi- 
ble value is associated with an ordinality, which is an integral value. Except 
for integer-type values, the first value of every ordinal-type has ordinality 0, 
the next has ordinality 1, and so on for each value in that ordinal-t3^e. An 
integer-type value's ordinality is the value itseE In any ordinal-type, each 
value other than the first has a predecessor, and each value other than the last 
has a successor based on the ordering of the type. 

The standard function Ord can be applied to any ordinal-type value to return 
the ordinality of the value. 

The standard function Pred can be appfied to any ordinal-type value to return 
the predecessor of the value. If applied to the first value in the ordinal-type, 
Pred produces an error. 

The standard function Succ can be appHed to any ordinal-type value to return 
the successor of the value. If applied to the last value in the ordinal-type, Sticc 
produces an error. 

The syntax of an ordinal-type follows. 



ordinal type 



^ subrange type 



enunrerated type 



■-^ ordinal type identifier 



Turbo Pascal has four predefined ordinal-types: Integer, Longint, Boolean, 
and Char, In addition, there are two other classes of user-defined ordinal-types: 
enumerated-types and subrange-types. 



The Integer-Type 

Integer-type values are a subset of the whole numbers. An integer-type variable 
can have a value within the -maxint-l to maxint range, that is, —32,768 to 
32,767. The standard Integer constant maxint is defined as 32,767. The range 
encompasses 16-bit, two's-complement integers. 



The Longlnt-Type 

Longint-type values are also a subset of the whole numbers, a larger subset. A 
longint-type variable can have a value within the -maxlongint-l to maxhngint 
range. The standard Lon^nt constant maxhngint is defined as +2,147,483,647. 
The range encompasses 32-bit, two's-complement integers. 
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Arithmetic operations with integer-type operands uses Integer (16-bit) or 
Longlnt (32-bit) precision according to the following rules: 

• Integer constants in the range of type Integer are considered to be of t3^e 
Integer. Other integer constants are considered to be of type Longlnt. 

• When both operands of an operator (or the single operand of a unary operator) 
are of type Integer, 16-bit precision is used, and the result is of type Integer 
(truncated to 16-bits if necessary). Similarly, if both operands are of type 
Longlnt, 32-bit precision is used, and the result is of type Longlnt. 

• When one operand is of type Longlnt, and the other is of type Integer, the 
Integer operand is converted to Longlnt, 32-bit precision is used, and the 
result is of type Longlnt. 

• The expression on the right of an assignment statement is evaluated indepen- 
dently of the size of the variable on the left. 

An Integer value may be explicitly converted to Longlnt (and vice versa) 
through type casting/Type casting is described in Chapers 19 and 20. 

The Boolean-Type 

Boolean-type values are denoted by the predefined constant identifiers FaZ^^ and 
True. Because Boolean is an enumerated-type, these relationships hold: False { 
True; Ord(False) = 0; Ord(True) = 1; Succ(False) = True; and Pred(True) = 
False, 

The Char-Type 

This type's set of values are characters, ordered according to the ordering of the 
Macintosh character set (Appendix F). The function call Ord(Ch), where Ch is a 
Char value, returns Ch's ordinality. 

A string constant of length 1 can denote a constant Char value. Any value of 
type Char can be generated with the standard function Chr, 

The Enumerated'Type 

Enumeratedrtypes define ordered sets of values by enumerating the identifiers 
that denote these values. Their ordering follows the sequence in which the iden- 
tifiers are enumerated. 



212 



Turbo Pascal for the Macintosh 



enumerated type ^CO H 




identifier list 



WD 



identifier list 




identifier 



When an identifier occurs within the identifier Hst of an enumerated-type, it 
is declared as a constant for the block in which the enumerated-type is declared. 
This constant's type is the enumerated-type being declared. 

An enumerated constant's ordinality is determined by its position in the iden- 
tifier list in which it is declared. The enumerated-type in which it is declared 
becomes the constant's type. The first enumerated constant in a list has an 
ordinality of 0 (zero). 

An example of enumerated-type is 

suit - (clubrCliainond,heart/Spade) 

Given these declarations, diamond is a constant of type suit. 

When the Ord function is applied to an enumerated-type's value, Ord returns 
an integer that shows where the value falls with respect to the other values of the 
enumerated-type. Given the declarations above, for example, Ord(club) returns 
0, Ord(diamond) returns 1, and so on. 

The Subrange-Type 

A subrange-type is a range of values from an ordinal-type called the host-type. 
The definition of a subrange-type specifies the least and the largest value in the 
subrange. Its syntax is 



Both constants must be of the same ordinal-type. Subrange-types of the form 
a.. require that a is less than or equal to b. 

Examples of subrange-types: 
o..sq 

club. .heart 

A variable of a subrange-type has all the properties of variables of the host- 
type, but its run-time value must be in the specified interval. 
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subrange type 




The Red-Type 



A real-type has a set of values that is a subset of real numbers, which you can 
represent in floating-point notation with a fixed number of digits. A value's float- 
ing-point notation normally comprises three values — m, b, and e — such that 
mxbe = n, where b is always 2 and both m and e are integral values within the 
real-type's range. These m and e values further prescribe the real-type's range 
and precision. 

Arithmetic with real-type values includes results that floating-point notation 
can't handle, such as dividing 0 by 0. Chapter 26 discusses the methods you can 
use for such specialized calculations. 

There are four kinds of real-types: Real, Double, Extended, and Comp. In 
addition, the type Single is identical to the type Real The real-types diflFer in the 
range and precision of values they hold: 



Table 18-1 Range and Decimal Digits for Real Types 



Type 


Range 




DecimaLJ>igits 


Real 


1.5 X 10" 


to 3.4 X 10^ 


7 to 8 


Double 


5.0 X 10 


to 1.7 X 10^« 


15 to 16 


Extended 


1.9 X 10" 


to 1.1 X 10'^^ 


19 to 20 



The Comp type holds only integral values within the range —2^-1-1 to 2^—1, 
which is approximately -9.2 X lO'® to 9.2 X lO''. 

All real-type values are converted to Extended before any operations are per- 
formed on them, and the results of such operations are always of type Extended. 
An Extended value may always be used where a Real, Double, or Comp value is 
required, provided that the value (rounded to an integral value in the case of 
Comp) falls within the required range. 

Note: Calculations on Extended type variables are faster and more compact 
than other real-type calculations, since the automatic conversion to Extended is 
not required. You may want to declare all real-type temporary variables, formal 
value parameters, and function results as Extended in order to improve execu- 
tion time and code size. 
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String-Types 



A string-type value is a sequence of characters with a dynamic length attribute 
(depending on the actual character count during program execution) and a con- 
stant size attribute from 1 to 255. A string-type declared without a size attribute 
is given the default size attribute 255. The length attribute s current value is 
returned by the standard function Length 



string type - 



string ) ■ 



"^^l^ — ► unsigned integer 



Ordering between any two string values is set by the ordering relationship of 
the character values in corresponding positions. In two strings of unequal length, 
each character in the longer string without a corresponding character in the 
shorter string takes on a higher or greater-than value; for example, 'Xs' is greater 
than 'X'. Null strings can only be equal to other null strings, and they hold the 
least string values. 

Characters in a string can be accessed as components of an array as described 
in "Arrays, Strings, and Indexes" in Chapter 19. String-type operators are 
described in ^String Operators'* and ''Relational Operators" in Chapter 20. 
String-type standard procedures and functions are described in Chapter 25. 



Structured-Types 



A structured-type, characterized by its structuring method and by its compo- 
nent-type(s), holds more than one value. If a component-type is structured, the 
resulting structured-type has more than one level of structuring. A structured- 
type can have unlimited levels of structuring. 



structured type 



> array type 



set type 



file type 



record type 



The word packed in a structured-type's declaration tells the compiler to com- 
press data storage, even at the cost of diminished access to a component of a 
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variable of this type. Only the storage of record-types and array-types can be 
packed. (String-types are always packed.) 

Packed only affects the representation of one level of the structured-type it 
occurs in. If a component is also a structured-type, then for it to be packed, its 
declaration must also include the word packed. 

You cannot use components of packed variables as actual variable parameters 
to procedures or functions. 



Array-Types 



Arrays have a fixed number of components of one type, the component-type. In 
the following syntax diagram, the component-type follows the word of 



array 
type 



array 



}--^T)y-» index type ^jKi)""K^D^ 



type 



index type ► ordinal type 



The index-types, one for each (unlimited) dimension of the array, specify the 
number of elements. The array can be indexed in each dimension by all values of 
the corresponding index-type; the number of elements is therefore the number 
of values in each index-type. Arrays may not occupy more than 32,767 bytes in 
total, and index-types may not be Longlnt or subranges of Longfnt, 

An example of an array-type is: 
arrayCl. .IDQ} of Heal 

If an array-type's component-type is also an array, you can treat the result as 
an array of arrays or as a single multi-dimensional array. For instance, 

array [Boolean] of arrayCL.ia] of arrayCSizel of Real 

is interpreted the same way by the compiler as 

arrayEBoolean/1. .lD,Slze] of Real 

You can also express 

packed array [1.. 103 of packed array [1.. a 1 of Boolean 

as 

packed array C 1. .IQ^l. .fi] of Boolean 
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You access an array's components by supplying the array's identifier with one 
or more indexes in brackets (see **Arrays, Strings, and Indexes'* in Chapter 19). 

An array-type of the form 
packed array El.. n] of. Char 

is called a packed-string-type. A packed-string-type has certain properties not 
shared by other array-types (see "Identical and Compatible Types" later in this 
chapter). 

Record-Types 



A record-type comprises a set number of components, or fields, which can be of 
different types. The record-type declaration specifies the type of each field and 
the identifier that names the field. 



record type — »'(^record ^ 



field list 



J 



field list 



^ fixed part 



variant part 



fixed part 



Identifier list 



type 



-Q- 
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The fixed-part of a recx)rd-type sets out the list of fixed fields, giving an identi- 
fier and a type for each. Each field contains information that is always retrieved 
in the same way. 

The following is an example of a record-type: 

record 

year: Integer; 
month: 

day: 1..31; 
end 

The variant-part shown in the previous syntax diagram distributes memory 
space for more than one list of fields, so the information can be accessed in more 
ways than one. Each list of fields is a variant. The variants overlay the same 
space in memory, and all fields of all variants can be accessed at all times. 



variant 
part 



►( case y 



# identifier 



tag field type -^^of^-x^ 



variant 




tag field type 



ordinal type identifier 



variant 



constant 



i-GKD- 



field lisTl-^ 
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As you can see from the diagram, each variant is identified by at least one 
constant. All constants must be distinct and of an ordinal-type that is compatible 
with the tag-field-rtype. Variant and fixed fields are accessed the same way. 

An optional identifier, the tag-field identifier, can be placed in the variant- 
part. If a tag-field identifier is present, it becomes the identifier of an additional 
fixed field, the tag-field, of the record. The program can use the tag-field's value 
to show which variant is active at a given time. Without a tag-field, the program 
selects a variant by another criterion. 

Some record-types with variants follow. 

record 

firstNamerlastName: strlngC^O]; 
birthDate: Date; 
case citizen: Boolean of 
true: (birthplace: stringC^Dl); 
false: (country: stringEEQ]; 

entryPort: string C5D]; 
entryDate: Date; 
exitDate: Date); 



record 

x,y: Real; 

case kind: Figure of 

rectangle: (height, width: Real); 
triangle: (sizel,sideE, angle: Real); 
circle: (radius: Real); 
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Set-Types 



A set- type's range of values is the powerset of a particular ordinal-type (the base- 
type). Each possible value of a set-type is a subset of the possible values of the 
base-type. 

A variable of a set-type can hold from none to all values of the set. 



set type — ^ set )— •( of 



ordinal type 



The base-type must not have more than 256 possible values. For that reason, 
the base-type of a set cannot be Integer or Longlnt. If the base-type of a set is an 
integer-type subrange, the upper and lower bounds of the subrange must be 
within the range 0 to 255. 

Set-type operators are described in "^Set Operators" in Chapter 20. "Set Con- 
structors* in the same chapter shows how to construct set values. 

Every set-type can hold the value [ ], called the empty set. 



File-Types 



A file-type consists of a linear sequence of components of one type, the compo- 
nent-type, which may be of any type except a file-type or any structured-type 
with a file-type component. The number of components is not set by the file- 
type declaration. 



file type 




The standard file-type Text signifies a file containing characters organized into 
lines. Textfiles use special input/output procedures, discussed in Chapter 24. 



Pointer-Types 



A pointer-type defines a set of values that point to dynamic variables of a speci- 
fied type called the base-type. A pointer- type variable contains the memory 
address of a dynamic variable. 
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pointer type 



— ^ base type 




base type — w type identifier 



If the base-type is an undeclared identifier, it must be declared in the same 
type declaration part as the pointer-type. 

You can assign a value to a pointer variable with the New procedure, the @ 
operator, or the Pointer function. The New procedure allocates a new memory 
area in the application heap for a dynamic variable and stores the address of that 
area in the pointer variable. The @ operator directs the pointer variable to the 
memory area containing any existing variable, including variables that already 
have identifiers. The Pointer function points the pointer variable to a specific 
memory address. 

The reserved word nil denotes a pointer-valued constant that does not point to 
anything. 

See Chapter 19 for the syntax of referencing the dynamic variable pointed to 
by a pointer variable. 

Identical and Compatible Types 



Two types may be the same, and this sameness (identity) is mandatory in some 
contexts. At other times, the two types need only be compatible or merely 
assignment compatible. They are identical when they are declared with, or their 
definitions stem from, the same type identifier. 

Type Identity 



Type identity is required only between actual and formal variable parameters in 
procedure and function calls. 

Two types — say, T^ and T^ — are identical if one of the following is true: T^ and 
Tg are the same type identifier; T^ is declared to be equivalent to a type identical 
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The second condition connotes that does not have to be declared directly to 
be equivalent to T^. The type declarations 

= Integer; 
T, - T,; 
T3 = Integer; 
T, = T,; 

result in T^, T^, T^, T^, and Integer as identical types. The type declarations 

T5 - set of Integer; 
= set of Integer; 

don't make T^ and T^ identical, since set of Integer is not a type identifier. Two 
variables declared in the same declaration, for example, 

Vj,, Vg: set of Integer; 

are of identical types — ^unless the declarations are separate. The declarations 

Vj^: set of Integer; 
Vg! set of Integer; 
V3 Integer; 
Integer; 

mean V3 and are of identical type, but not and V^. 
Compatibility of Types 



Compatibility between two types is sometimes required, such as in expressions 
or in relational operations. Type compatibility is important, however, as a pre- 
condition of assignment compatibility. Types compatibility exists when at least 
one of the following conditions is true: 

• Both types are the same. 

• Both types are real-types. 

• Both types are integer-types. 

• One type is a subrange of the other. 

• Both types are subranges of the same host-type. 

• Both types are set-types with compatible base-types. 

• Both types are packed-string-types with an identical number of components. 

• One type is a string-type and the other is a string-type, packed-string-type, or 
char-type. 
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Assignment Compatibility 



Assignment compatibility is necessary when a value is assigned to something, 
such as in an assignment statement or in passing value parameters. 

A value of type is assignment compatible with a type (that is, : = is 
allowed) if any of the following are true: 

• and are identical types and neither is a file-type or a structured-type that 
contain a file-type component at any level of structuring. 

• Tj and are compatible ordinal- types, and the values of type falls within 
the range of possible values of T^. 

• and are real-types, and the value of type falls within the range of 
possible values of T^. 

• Tj is a real- type, and is an integer-type. 

• and are string-types. 

• Tj is a string-type, and is a char- type. 

• Tj is a string-type, and is a packed-string-type. 

• Tj and are compatible packed-string-types. 

• and are compatible set-types, and all the members of the value of type 
fall within the range of possible values of T^. 

A compile or run-time error occurs when assignment compatibility is neces- 
sary and none of the above is true. 
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The Type Declaration Part 



Programs, procedures, and functions that declare types have a type declaration 
part. An example of this part follows: 



type 

Range 

Number 

Color 

Testlndex 

TestValue 

TestList 

TestListPtr 

Date 



HeasureData 



MeasureList 

Naie 

Sex 

Person 
PersonData 



People = file 
IntFile = file 



Integer; 
Integer; 

(red, green, blue) ; 
I.-IOD; 

array [Testlndex] of TestValue; 

'^TestList; 

record 

year: Integer; 

month: L.IS; 

day: 1..31; 
end; 
record 

when: Date; 

count: Testlndex; 

data: TestListPtr; 
end; 

array[1..5D] of MeasureData; 

string[flD] ; 

(male, female) ; 

*PersonDetails; 

record 

naie/firstName: Name; 

age: Integer; 

married: Boolean; 

father, child, sibling: Person; 

case s: Sex of 
male: (bearded: Boolean); 
female: (pregnant: Boolean); 

end; 
of PersonData; 
of Integer 



In the example Range, Number, and Integer are identical types. Testlndex is 
compatible and assignment compatible with, but not identical to, the types 
Number, Range, and Integer, 
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CHAPTER 



Variables 



Variable Declarations 



A variable declaration embodies a list of identifiers that designate new variables 
and their type. 



variable declaration — identifier list — — ^ 



The type given for the variable(s) can be a type identifier previously declared 
in a type declaration part in the same block, in an enclosing block, or in a unit, or 
it can be a new type definition. 

When an identifier is specified within the identifier list of a variable declara- 
tion, that identifier is a variable identifier for the block in which the declaration 
occurs. The variable can then be referred to throughout the block, unless the 
identifier is redeclared in an enclosed block. Redeclaration causes a new variable 
using the same identifier, without aflFecting the value of the original variable. 
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An example of a variable declaration part follows: 
var 

X,Y,Z: Real; 
I,J,K: Integer; 
Digit: D..'^; 
C: Color; 

Done, Error: Boolean; 

Operator: (plus, minus, times); 

Huel,Huea: set of Color; 

Today: Date; 

Results: MeasureList; 

P1,P2: Person; 

Matrix: arrayLl. .10,1. .ID] of Real; 



Variable References 



A variable reference signifies one of the following: 

• a variable 

• a component of a structured-type or string-type variable 

• a dynamic variable pointed to by a pointer-type variable 

The syntax for a variable reference is 



variable reference 



variable identifier 



variable type cast 



I ttj J 

— I H qualifier N-> 



Qualifiers 



A variable reference is a variable identifier with zero or more qualifiers, which 
modify the meaning of the variable reference. 



qualifier 



index 



field designator 



U(A> 
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An array identifier with no qualifier, for example, references the entire array: 
Results 

An array identifier followed by an index denotes a specific component of the 
array — in this case a structured variable: 

Results[Current+l] 

With a component that is a record, the index may be followed by a field desig- 
nator; here the variable access signifies a specific field within a specific array 
component. 

ResultsCCurrent+1] .data 

The field designator in a pointer field may be followed by the pointer symbol, 
^ (a caret), to difierentiate between the pointer field and the dynamic variable it 
points to. 

ResultsCCurrent+1] .data*" 

If the variable being pointed to is an array, indexes can be added to denote 
components of this array. 

Results [Current+1]. data'* [J] 
ArraySy Strings, and Indexes 



A specific component of an array variable is denoted by a variable reference that 
refers to the array variable, followed by an index that specifies the component. 

A specific character within a string variable is denoted by a variable reference 
that refers to the string variable, followed by an index that specifies the character 
position. 



The index expressions select components in each corresponding dimension of 
the array. The number of expressions can't exceed the number of index-types in 
the array declaration. Furthermore, each expression's type must be assignment 
compatible with the corresponding index- type. 

When indexing a multi-dimensional array, multiple indexes or multiple 
expressions within an index can be used interchangeably. For example, 

MatrixCI][J] 
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index 




is the same as 
MatrixCIrJ] 

You can index a string variable by a single index expression, whose value must 
be in the range 0. . n, where n is the declared size of the string. This accesses one 
character of the string value, with the type Char given to that character value. 

The first character of a string variable (at index 0) contains the dynamic length 
of the string; that is, Length(S ) is the same as Ord(S[0]). If a value is assigned to 
the length attribute, the compiler does not check that this value is less than the 
declared size of the string. It is possible to index a string beyond its current 
dynamic length. The characters thus read are random, and assignments beyond 
the current length will not aflFect the actual value of the string variable. 

Records and Field Designators 



A specific field of a record variable is denoted by a variable reference that refers 
to the record variable, followed by a field designator specifying the field. 



Some examples of field designators: 

Today. year 
EesultsCl] .count 
ResultsCl] .when. month 

In a statement within a with statement, a field designator does not have to be 
preceded by a variable reference to its containing record. 

Pointers and Dynamic Variables 



The value of a pointer variable is either nil, or a value that points to a dynamic 
variable. 

The dynamic variable pointed to by a pointer variable is referenced by writing 
the pointer symbol ^ after the pointer variable. 

You create dynamic variables and their pointer values with the standard proce- 
dure New. The @ operator and standard procedure Pointer can be employed to 
create pointer values that are treated as pointers to dynamic variables. 

nil does not point to any variable. It is an error if you access a dynamic variable 
when the pointer s value is nil or undefined. 



field designator 
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Some examples of references to dynamic variables: 

PI*. sibling* 
Results [11. data* 



Variable-Type-Casts 



A variable reference of one type can be changed into a variable reference of 
another type through a variable-type-cast. 



variable type cast ^ type identifier — variable reference —^(T) — ► 



When a variable-type-cast is applied to a variable reference, the variable 
reference is treated as an instance of the type specified by the type identifier. 
The size of the variable (the number of bytes occupied by the variable) must be 
the same as the size of the type denoted by the type identifier. A variable-type- 
cast may be followed by one or more quahfiers as allowed by the specified type. 

Some examples of variable-type-casts: 

type 
Point = record 

x,y: Integer; 
end; 

List = arrayCL.a] of Integer; 
var 

P: Point; 
L: Longint; 
N: Integer; 
begin 

P := Point(L); 
N := Point{L).x; 

Longlnt(P) := Longint(P) + SDDQflDDDfl; 
List(P)CN] :« 32; 
end. 

Turbo Pascal also allows you to type cast the value of an expression. This is 
described in Chapter 20. 
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CHAPTER 



Expressions 



Expressions are made up of operators and operands. Most Pascal operators are 
binary, that is, they take two operands; the rest are unary and take only one 
operand. Binary operators use the usual algebraic form, for example, a+fo. A 
unary operator always precedes its operand, for example, —b. 

In more complex expressions, rules of precedence clarify the order in which 
operations are performed. Table 20-1 shows the precedence of operators. How- 
ever, there are three basic rules of precedence. First, an operand between two 
operators of different precedence is bound to the operator with higher prece- 
dence. Second, an operand between two equal operators is bound to the one on 
its left. Third, expressions within parentheses are evaluated prior to being 
treated as a single operand. 



Table 20-1 Precedence of Operators 



Operators 


Precedence 


Categories 


@, not 


highest 


unary operators 


* , /, div, mod, and, shl, shr 


second 


multiplying operators 


+ ,-, or, xor 


third 


adding operators 


= , 0, <, ), <=, >=, in 


lowest 


relational operators 



Operations with equal precedence are normally performed from left to right. 
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Expression Syntax 



The precedence rules follow from the syntax of expressions, which are built from 
factors, terms, and simple-expressions. 

The syntax of a factor is 



factor 



^ unsigned constant 



U0- 



variable reference 



» | procedure identifier 



function identifier 



expression 



-^^noTy-^ 



factor 



function call 



set constructor 



value type cast 
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A function call activates a function, and denotes the value returned by the 
function (see ^'Function Calls** later in this chapter). A set constructor denotes a 
value of a set type (see "Set Constructors'*). A value-type-cast changes the type of 
a value (see *'Value-Type-Casts''). An unsigned constant has the following syntax: 



unsigned constant 



^ unsigned number 



character string 



constant identifier 



Some examples of factors: 



X 

9X 

15 

(X+Y+Z) 
Sin(X/5) 

not Done 
Char(Digit+<fl) 



'A' 



Z'] 



{variable reference} 
{pointer to a variable} 
{unsigned constant} 
{subexpression} 
{function call} 
{set constructor} 
{negation of a boolean} 
{value-type-cast} 
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Terms apply the multiplying operators to factors: 



term 



factor 




-(m^ 



Some examples of terms: 

Z/{l-Z) 

Done or Error 

{X <= Y) and (Y < Z) 

Simple expressions apply adding operators and signs to terms: 
simple expression 



L-^ sign — I 



term 



-O- 



Some examples of simple expressions: 



X+Y 

-X 

HueX + Hue5 
I*J + 1 
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An expression applies the relational operators to simple expressions: 
expression — 



simple expression 



---^^ — y» j simple expression 




Some examples of expressions: 



X = 1.5 

Done <> Error 

(I < J) = (J < K) 
C in Huel 



Operators 



The operators are classified as arithmetic operators, logical operators, string 
operators, set operators, relational operators, and the @ operator. 



Arithmetic Operators 



The following tables show the types of operands and results for binary and unary 
arithmetic operations. 
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Table 20-2 Binary Arithmetic Operations 



Operator 


Operation 


Operand Types 


Type of Result 


+ 


addition 


integer-type 
real-type 


integer-type 
Extended 




subtraction 


integer-type 
real-type 


integer-type 
Extended 




multiplication 


integer-type 
real-type 


integer-type 
Extended 


/ 


division 


integer-type 
real-type 


Extended 
Extended 


div 


integer division 


integer-type 


integer-type 


mod 


remainder 


integer-type 


integer-type 



NOTE: The + operator is also used as a string or set operator, and the — and 
* operators are also used as set operators. 



Table 20-3 Unary Arithmetic Operations 



Operator 


Operation 


Operand Types 


Type of Result 


+ 


sign identity 


integer-type 


integer-type 






real-type 


Extended 




sign negation 


integer-type 


integer-type 






real-type 


Extended 



Any operand whose type is a subrange of an ordinal-type is treated as if it 
were of the ordinal-type. 

If both operands of a +, — , *, div, or mod operator are of type Integer, the 
result is of type Integer. If one or both operands are of type Longint, the result is 
of type Longlnt. 

If one or both operands of a +, — , or * operator are of a real-type, the type of 
the result is Extended. 

If the operand of the sign identity or sign negation operator is of an integer- 
type, the result is of the same integer-type. If the operator is of a real-type, the 
type of the result is Extended. 

The value of x/y is always of type Extended, regardless of the operand types. 
An error occurs if 1/ is zero. 

The value of i div j is the mathematical quotient of i/j, rounded in the direction 
of zero to an integer-type value. An error occurs if j is zero. 

The mod operator returns the remainder obtained by dividing its two oper- 
ands, that is, 

i lod ] - i - (i div j) * j 
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The sign of the result of mod is the same as the sign of i. An error occurs if j is 
zero. 

Logical Operators 



The types of operands and results for logical operations are shown inTable 20-4. 





Table 20-4 


Logical Operations 




Operator 


Operation 


Operand Types 


Type of Result 


not 


negation 


Boolean 


Boolean 




bitwise negation 


integer-type 


integer-type 


and 


logical and 


Boolean 


Boolean 




bitwise and 


integer-type 


integer-type 


or 


logical or 


Boolean 


Boolean 




bitwise or 


integer-type 


integer-type 


xor 


logical xor 


Boolean 


Boolean 




bitwise xor 


integer-type 


integer-type 


shl 


shift left 


integer-type 


integer-type 


shr 


shift right 


integer-type 


integer-type 



Note: The not operator is a unary operator. 

For operands of type Boolean, normal boolean logic governs the results of 
these operations. For instance, a and h is True only if both a and h are true. 

If the operand of the not operator is of an integer-type, the result is of the 
same integer-type. 

If both operands of an and, or, or xor operator are of type Integer, the result is 
of type Integer, If one or both operands are of type Longlnt, the result is of type 
Lon^nt, 

The operations i s\Aj and i shr j shifts the value of i to the left or to the right by 
j bits. The type of the result is the same as the type of f. 
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String Operators 



The types of operands and results for string operations are shown in Table 20-5. 





Tabh20-5 


String Operations 




Operator 


Operation 


Operand Types 


Type of Result 


+ 


concatenation 


string-type, char-type, 
or packed-string-type 


string-type 



Turbo Pascal allows the + operator to be used to concatenate two string oper- 
ands. The result of the operation s-\-t, where s and t are of a string- type, a char- 
type, or a packed-string-type, is the concatenation of s and t. The result is com- 
patible with any string- type (but not with char-types and packed-string- types). If 
the resulting string is longer than 255 characters, it is truncated after the 255th 
character. 

Set Operators 



The types of operands for set operations are shown in Table 20-6. 





Table 20-6 


Set Operations 


Operator 


Operation 


Operand Types 




union 


compatible set-types 




difference 


compatible set-types 


* 


intersection 


compatible set-types 



The results of set operations conform to the rules of set logic: 

• An ordinal value c is in a+fe only if c is in a or fc. 

• An ordinal value c is in a—b only if c is in a and not in b. 

• An ordinal value c is in a*fo only if c is in both a and b. 

If the smallest ordinal value that is a member of the result of a set operation is 
a and the largest is b, then the type of the result is set of a. 



238 



Turbo Pascal for the Macintosh 



Relational Operators 



The types of operands and results for relational operations are shown in 
Table 20-7. 



Table 20-7 Relational Operations 



Operator 


Operation 


Operand Types 


Type of Result 




equal 


compatible simple, pointer, set, 

9 LI 111^, yjl L/dV^IVt/ V-l o LI 111^ L y LIC^O 


Boolean 


A 
\/ 




V^Uill LydLlUlC/ OliJ.lLIAV7j L^VJXllLV^l, OC/I, 

string, or packed-string types 






less than 


compatible simple, string, or 
packed-string types 


Boolean 




greater than 


compatible simple, string, or 
packed-string types 


Boolean 




less or equal 


compatible simple, string, or 
packed-string types 


Boolean 




greater or equal 


compatible simple, string, or 
packed-string types 


Boolean 




subset of 


compatible set-types 


Boolean 




superset of 


compatible set-types 


Boolean 


in 


member of 


left operand: any ordinal- type t 
right operand: set of type t 


Boolean 



Comparing Simple-Types 

When the operands of =, {), {, ), )=, or (= are of simple-types, they must be 
compatible types, except that if one operand is of a real-type the other may be of 
an integer-type. 

Because real-type values are approximations, the results of comparing real- 
type values are not always as expected. For instance, if X is a variable of type 
Real and Y is a variable of type Double, and if the assignments 

X := 1/3; 
Y 1/3; 

have been made, then X=Y will return False. The reason is that X is accurate 
only to 7 to 8 digits, whereas Y is accurate to 15 to 16 digits, and when both are 
converted to Extended, they will diflFer after 7 to 8 digits. 

See Chapter 26, for extensions that aflPect the ordering of comparisons involv- 
ing NaNs. 
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Comparing Strings 

The relational operators =,(),(,),)=, and (= compare strings according to the 
ordering of the Macintosh character set. Any two string values can be compared, 
since all string values are compatible, 

A char-type value is compatible with a string-type value, and when the two are 
compared, the char-type value is treated as a string-type value with length 1. 
When a packed-string-type value with n components is compared with a string- 
type value, it is treiated as a string-type value with length n. 

Comparing Packed Strings 

The relational operators =, 0> (> )» )=> (= may also be used to compare two 
packed-string-type values if both have the same number of components. If the 
number of components is n, then the operation corresponds to comparing two 
string each of length n. 

Comparing Pointers 

The operators = and () can be used on compatible pointer-type operands. Two 
pointers are equal only if they point to the same object. 

Comparing Sets 

If a and b are set operands, their comparisons produce these results: 

• fl = fo is true only if a and b contain exactly the same members; otherwise, 
a Ob. 

• a{= h is true only if every member of a is also a member of b, 

• a)= b is true only if every member of b is also a member of a. 

Testing Set Membership 

The in operator returns True when the value of the ordinal-type operand is a 
member of the set-typed operand; otherwise, it returns False, 
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The @ Operator 



A pointer to a variable can be created with the @ operator. Table 20-8 shows the 
operand and result types. 



Table 20-8 Pointer Operations 



Operator 


Operation 


Operand Types 


Type of Result 


@ 


pointer formation 


variable reference or 


pointer (same as nil) 






procedure or Unction 








identifier 





@ is a unary operator that takes a variable reference or a procedure or function 
identifier as its operand returns a pointer to the operand. The type of the value is 
the same as the type of nil, therefore it can be assigned to any pointer variable. 



@ with a Variable 

The use of @ with an ordinary variable (not a parameter) is uncomplicated. 
Given the declarations: 

type 

TwoChar = packed array CO.. 11 of Char; 
var 

Int: integer; 
TwoCharPtr: *TwoChar; 

then the statement: 
TwoCharPtr := @Int; 

causes TwoCharPtr to point to Int. TwoCharPtr^ becomes a reinterpretation of 
the value of int, as though it were a packed array [0.,1] of Char. 

@ with a Value Parameter 

Applying @ to a formal value parameter results in a pointer to the stack location 
containing the actual value. Say Foo is a formal value parameter in a procedure 
and FooPtr is a pointer variable. If the procedure executes the statement: 

FooPtr := @Foo; 

then FooPtr^ references Foo's value. However, FooPtr^ does not reference Foo 
itself but rather it references the value that was taken from Foo and stored on 
the stack. 
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@ toith a Variable Parameter 

Applying @ to a formal variable parameter results in a pointer to the actual, 
parameter (the pointer is taken from the st^k). Say One is a formal variable 
parameter of a procedure, Ttvo is a variable passed to the procedure as Ones 
actual parameter, and OnePtr is a pointer variable. If the procedure executes the 
statement 

OnePtr := ©One; 

then OnePtr is a pointer to Ttoo and OnePtr^ is a reference to Two itself 



@ with a Procedure or Function 

You can apply @ to a procedure or a function to produce a pointer to its entry 
point. Turbo Pascal does not give you a mechanism for using such a pointer. The 
only use for a procedure pointer is to pass it to an assembly-language routine. 



Function Calls 



A function call activates the function specified by the function identifier. Any 
identifier declared to denote a function is a function identifier. 

The function call must have a list of actual parameters if the corresponding 
function declaration contains a list of formal parameters. Each parameter takes 
the place of the corresponding formal parameter according to parameter rules set 
forth in Chapter 22. 



function call 



function identifier 



actual parameter list 



actual parameter list 



actual parameter 



actual parameter 



expression 



^ variable reference 
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Some examples of function calls follow: 

Suin(A,t3) 
Maximuiii(1^7,J) 
Sin(X+T) 
Eof{F) 

Volume ( Radius , Height ) 



Set Constructors 



A set constructor denotes a set-type value, and is formed by writing expressions 
within brackets ([]). Each expression denotes a value of the set. 



set constructor 



jr-^ member group 



member group 




The notation [] denotes the empty set, which is assignment compatible with 
every set-type. Any member group x.,y denotes as set members all values in the 
range x.,y. If x is greater than t/, then x..y does not denote any members and 
[x..y] denotes the empty set. 

All expression values in member groups in a particular set constructor must be 
of the same ordinal- type. 

Some examples of set constructors follow: 

Credr Cf green] 

[1, 5, 1D..K mod IE/ 53] 

['a'..'Z'r 'a'..'z', Chr.(Digit+^fl)] 
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VaJue-'Type-Casts 



The type of an expression can be changed to another type through a value-type- 
cast. 



value typecast 



type identifier 



expression 



The expression argument must be of an ordinal-type or a pointer- type. The 
result is of the specified type, and its ordinal value is obtained by converting the 
expression. This conversion may involve truncation or extension of the original 
value if the size of the specified type is difierent from that of the expression. In 
cases where the value is extended, the sign of the value is always preserved, that 
is, the value is sign-extended. 

The syntax of a value-type-cast is almost identical to that of a variable-type- 
cast see ^'Variable-Type-Casts" in Chapter 19. However, value-type-casts operate 
on values, not on variables, and can therefore not participate in variable refer- 
ences; that is, a value-type-cast may not be followed by qualifiers. In particular, 
value-type-casts may not appear on the left-hand side of an assignment state- 
ment. 

Some examples of value-type-casts: 

Integer('A') Char(<fl) Boolean(D) Color(5) 

Longint(®Buffer) IntPtr(-l) IntPtr(LongInt(P)+E) 
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CHAPTER 



Statements 



Statements describe algorithmic actions that can be executed. Labels can prefix 
statements, and these labels can be referenced by goto statements. 



statement 



label 



simple statement 



structured statement 



As you saw in Chapter 16, a label is either a digit sequence in the range 0 to 
9999 or an identifier. 

There are two main types of statements: simple statements and structured 
statements. 



Simple Statements 



A simple statement is a statement that does not contain any other statements, 
simple statement 



assignment statement 



procedure statement 



^ goto statement 
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Assignment Statements 



Assignment statements either replace the current value of a variable with a new 
value specified by an expression or specify an expression whose value is to be 
returned by a function. 



assignment statement 



variable reference 



function identifier 




expression 



The expression must be assignment compatible with the type of the variable 
or the result type of the function (see Chapter 18, "Compatibility of Types'"). 

Some examples of assignment statements: 



X 

Done 
Huel 
I 



Y+Z ' 

(I>=1) and (KIDD); 
tblue,Succ(C) 3 ; 
Sqr{J) - I*K; 



Procedure Statements 



A procedure statement specifies the activation of the procedure denoted by the 
procedure identifier. If the corresponding procedure declaration contains a list of 
formal parameters, then the procedure statement must have a matching list of 
actual parameters (parameters fisted in definitions are formal parameters; in the 
calling statement, they are actual parameters). The actual parameters are passed 
to the formal parameters as part of the call. 



procedure statement 



procedure identifier 



actual paramet&r list 



Some examples of procedure statements: 

PrintHeading; 
Transpose { A, N,M) ; 
Find(Naiiie, Address) ; 
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Goto Statements 



A goto statement transfers program execution to the statement prefixed by the 
label that is referenced in the goto statement. Following is the syntax diagram of 
a goto statement: 



goto statement 




The following rules should be observed when using goto statements: 

• The label referenced by a goto statement must be in the same block as the goto 
statement. In other words, it is not possible to jump into or out of a procedure 
or function. 

• Jumping into a structured statement from outside that structured statement 
(that is, jumping to a "deeper'' level of nesting) can have undefined eflfects, 
although the compiler will not indicate an error. 



Structured Statements 



Structured statements are constructs composed of other statements that are to 
be executed in sequence (compound statements and with statements), condition- 
ally (conditional statements), or repeatedly (repetitive statements). 



structured statement 



> compound statement 



conditional statement 



repetitive statement 



with statement 



Compound Statements 



The compound statement specifies that its component statements are to be exe- 
cuted in the same sequence as they are written. The component statements are 
treated as one statement, crucial in contexts where the Pascal syntax only allows 
one statement. Begin and end bracket the statements, which are separated by 
semicolons. 
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compound statement 




An example of a compound statement is 

begin 

Z X; 

X := Y; 

Y - Z; 



Conditional Statements 



A conditional statement selects for execution a single one (or none) of its compo- 
nent statements. 



conditional statement 





if statement 




















1 — ► 


case statement 













If Statements 

The syntax for if statements is 



if statement 



expression 



then } -» 



statement 




else] 



statement 



The expression must yield a result of the standard type Boolean, If the expres- 
sion produces the value True, then the statement following then is executed. 

If the expression produces False and the else part is present, the statement 
following else is executed; if the else part is not present, nothing is executed. 

The syntactic ambiguity arising from the construct 
if el then if eE then si else sd 
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is resolved by interpreting the construct as follows: 

if el then 
begin 
if eB then 

si 
else 
sE 

end 

In general, an else is associated with the closest if not already associated with 
an else. 

Two examples of if statements follow: 

if X < 1.5 then 

Z := X+Y 
else 

Z 1.5; 

if PI <> nil then 

PI := PI. father; 



Case Statements 

The case statement consists of an expression (the selector) and a list of state- 
ments, each prefixed with one or more constants (called case constants) or with 
the word otherwise. The selector must be of an ordinal-type, and all the case 
constants must be unique and of an ordinal-type that is compatible with the type 
of the selector. 



— ►^case ^ — ► expression 




case 












T 1 1 X m indT) — 



otherwise clause 



case 



constant 



constant 



■o 



0[ 



statement 



otherwise clause 



otherwise 



statement 
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The case statement executes the statement prefixed by a case constant that 
equals the value of the selector or a case range that contains the value of the 
selector. If no such case constant of the case range exists and an otherwise part is 
present, the statement following otherwise is executed. If there is no otherwise 
part, nothing is executed. 

Examples of case statements follow: 

case Operator of 

plus: X := X+Y; 

minus: X := X-Y; 

times: X := X*Y; 
end; 

case I of 

D,S,4,t,fl: WriteLnCEven digit'); 

l,3,5,7,q: HriteLnCOdd digit'); 

lD..iaa: WriteLn{ 'Between ID and IDD'); 
otherwise 

WriteLn( 'Negative or greater than IDD'); 
end; 



Repetitive Statements 



Repetitive statements specify that certain statements are to be executed repeat- 
edly. 



repetitive statement 



repeat statement 



while statement 



^ for statement 



If the number of repetitions is known beforehand, the for statement is the 
appropriate construct. Otherwise, the while or repeat statement should be used. 



Repeat Statements 

A repeat statement contains an expression that controls the repeated execution 
of a statement sequence within the repeat statement. 



repeat^ 
statement 



repeat 



statement 



>^ until J— ► 



expression 
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The expression must produce a result of type Boolean, The statements 
between the symbols repeat and until are executed in sequence until, at the end 
of a sequence, the expression yields True. The sequence is executed at least 
once, because the expression is evaluated after the execution of each sequence. 

Examples of repeat statements: 

repeat 

K := I nod J; 

I J; 

J := K; 
antll J » □; 

repeat 

Write( 'Enter value (D..q): 
fieadLn(I); 
nntil (I D) and (I <= 1); 



While Statements 

A while statement contains an expression that controls the repeated execution of 
a statement (which may be a compound statement). 



white statement 



^ while 



expression | — »(do^ — » statement 



The expression controlling the repetition must be of type Boolean. It is evalu- 
ated before the contained statement is executed. The contained statement is 
executed repeatedly as long as the expression is True, If the expression is False at 
the beginning, the statement is not executed at all. 

Examples of while statements: 
while DataCIlo X do I I + 1; 

vhlle I > 0 do 
begin 

if Odd(I) then Z Z » X; 
I := I div 2; 
X :» Sqr(X); 
end; 

while not Eo£(InFile) do 
begin 

ReadLn(InFilerLine) ; 
Process (Line); 
end; 
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For Statements 



The for statement causes a statement (which may be a compound statement) to 
be repeatedly executed, while a progression of values is assigned to a variable 
called the control variable. 



for statement 



control variable 



initial value 



-K»> 



downto 



final value 



statement 



control variable 
Initial value 



variable identifier 



^ 


expression 









final value 



expression 



The control variable must be a variable identifier (without any qualifier) that 
signifies a variable declared to be local to the block containing the for statement. 
The control variable must be of an ordinal-type. The initial and final values must 
be of a type that is assignment compatible with the ordinal-type. 

When a for statement is entered, the initial and final values are determined 
once for the remainder of the execution of the for statement. 

The statement contained by the for statement is executed once for every value 
in the range initial-value to final-value. The control variable always starts oflFat 
initial-value. With a for statement using to, the value of the control variable is 
incremented by one for each repetition. If inittaUvalue is greater than^^naZ- 
value, the contained statement is not executed. With a for statement using 
downto, the value of the control variable is decremented by one for each repeti- 
tion. If initialrvalue value is less ihanfinal-valuei the contained statement is not 
executed. 

It is an error if the contained statement alters the value of the control variable. 
After a for statement is executed, the value of the control variable value is unde- 
fined, unless execution of the for statement was interrupted by a goto out of the 
for statement. 

With these restrictions in mind, the for statement 
for V :^ Exprl to ExprE do Body; 
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is equivalent to 

begin 

Tempi := Exprl; 

TempE := ExprE; 

if Tempi <= TempS then 

begin 

V := Tempi; 
Body; 

while V <> TempE do 
begin 

V := Succ(V); 
Body; 

end; 
end; 
end; 

and the for statement 

for V Exprl downto ExprE do Body; 

is equivalent to 

begin 

Tempi := Exprl; 

TempE := ExprS; 

if Tempi >= TempE then 

begin 

V := Tempi; 
Body; 

while V <> TempE do 
begin 

V := Pred(V); 
Body; 

end; 
end; 
end; 

where Tempi and Temp2 are auxiliary variables of the host-type of the variable V 
that do not occur elsewhere in the program. 

Examples of for statements follow: 

for I := a to b3 do 
if Data[I] > Max then Max := DataEI] 

for I := 1 to ID do 
for J := 1 to 10 do 
begin 
X D; 

for K := 1 to ID do 

X := X + Matl[I,K] * Mata[K/Jl; 
Mat[I,J] := X; 
end; 

for C := red to blue do Check(C); 
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With Statements 



The with statement is a shorthand method for referencing the fields of a record. 
Within a with statement, the fields of one or more specific record variables can 
be referenced using their field identifiers only. The syntax of a with statement is 



with ^ 

statement % with 




record variable reference 



(do) 



statement 



record variable reference 



variable reference 



Following is an example of a with statement: 

with Date do 
if month = 15 then 
begin 

month := 1; 
year := year + 1 
end else 
month := month + 1; 

This is equivalent to 

if Date. month - 12 then 
begin 

Date. month := 1; 

Date. year := Date. year + 1 
end else 

Date. month := Date. month + 1; 

Within a with statement, each variable reference is first checked as to whether 
it can be interpreted as a field of the record. If so, it is always interpreted as 
such, even if a variable with the same name is also accessible. Suppose the 
following declarations have been made: 

type 
Point = record 

x,y: Integer; 
end; 

var 

x: Point; 
y: Integer; 

In this case, both x and y can refer to a variable or to a field of the record. In 
the statement 

with X do 
begin 

X := ID; 
y - 25; 
end; 
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the X between with and do refers to the variable of type Point, but in the com- 
pound statement, x and y refer to x.x and x.y. 

The statement 

with Vj,,Vg, ... do s; 

is equivalent to: 

with V, do 
with Vg do 

with V„ do 

S; 

In both cases, if is a field of both and V^, it is interpreted as V^.V^, not V^. 
V. " 

n 

If the selection of a record variable involves indexing an array or dereferencing 
a pointer, these actions are executed once before the component statement is 
executed. 
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c 



H 



A 



P 



T 



E 




Procedures and Functions 



Procedures and functions allow you to nest additional blocks in the main program 
block. Each procedure or function declaration has a heading followed by a block. 
A procedure is activated by a procedure statement; a function is activated by the 
evaluation of an expression that contains its call and returns a value to that 
expression. 

This chapter discusses the diflFerent types of procedure and function declara- 
tions and their parameters. 

Procedure Declarations 



A procedure declaration associates an identifier with a block as a procedure; that 
procedure then can be activated by a procedure statement. 



procedure 
declaration 



procedure heading procedure body 
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parameter type — i ^ type identifier — j- 

' ^string ) 



procedure body 



blocl^ 



forward^ 
external^ 



inline body 



inline body 



inline 



constant 



The procedure heading names the procedure's identifier and specifies the 
formal parameters (if any). 



procedure 
heading 



— »^procedure 



identifier 



formal parameter list 



The syntax for a formal parameter list is shown under ^Parameters" later in 
this chapter. 

A procedure is activated by a procedure statement, which states the proce- 
dure's identifier and any actual parameters required. The statements to be exe- 
cuted upon activation are noted in the statement part of the procedure's block. If 
the procedure's identifier is used in a procedure statement within the proce- 
dure's block, the procedure is executed recursively (that is, it calls itself while 
executing). 

Here's an example of a procedure declaration: 

procedure NumStringXN: Integer; var S: string); 
var 

V: Integer; 
l)egln 

V Abs(N); 

S := "; 

repeat 

S := Chr{N aod ID + Ord('D')) + S; 
N := N div ID; 
until N = 0; 

if N < D then S := '-' + S; 
end; 
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Instead of the block in a procedure or function declaration, you can write a 
forward, external, or inline declaration. 

Forward Declarations 



A procedure declaration that specifies the directive forward instead of a block is 
2i forward declaration. Somewhere after this declaration, the procedure must be 
defined by a defining declaration — ^a procedure declaration that uses the same 
procedure identifier, but omits the formal parameter list and includes a block. 
The forward declaration and the defining declaration must appear in the same 
procedure and function declaration part. Other procedures and functions can be 
declared between them, and they can call the forwardly declared procedure. 
Mutual recursion is thus possible. 

The forward declaration and the defining declaration constitute a complete 
declaration of the procedure. The procedure is considered declared at the for- 
ward declaration. 

An example of a forward declaration follows, 
procedure Walter(m,n: Integer); forward; 

procedure Clara(x,y: Real); 
begin 

Walter(^,5); 

end; 

procedure Halter; 
begin 

Clara(fl.3,a.-^); 

end; 

Forward declarations are not allowed in the interface part of a unit. 

External Declarations 



External declarations allow you to interface with separately compiled procedures 
and functions written in assembly language. The external code must be linked 
with the Pascal program or unit through {$L FileName} directives. For further 
details on linking with assembly language, refer to Chapter 27. 
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Examples of external procedure declarations follow: 
{$L BlockStuff.Rel} 

procedure MoveWord(var source, dest; count: Longlnt); external; 
procedure HoveliOngivar sourcerdest; count: Longlnt); external; 

procedure FillWord(var dest; data: Integer; count: Longlnt); external; 
procedure FillLong(var dest; data: Longint; count: Longlnt); external; 

You should use external procedures when you need to incorporate substantial 
amounts of assembly code. If you only require small amounts of code, use inline 
procedures instead. 



Inline Declarations 



The inline directive permits you to write machine code instructions instead of 
the block. The code consists of constants, typically written in hexadecimal nota- 
tion. 

When a normal procedure is called, the compiler generates code that pushes 
the procedure's arguments on the stack, and then generates a JSR (Jump to 
SubRoutine) instruction to call the procedure. When you "call" an inline proce- 
dure, the compiler generates code from the constants following inline instead of 
the JSR. Each constant represents exactly one word in the code generated by the 
compiler. The code is generated in the order of the constants. 

Use inline procedures, rather than external procedures, for writing small rou- 
tines. 

Example of an inline procedure: 
procedure Trap(Tos: Longlnt); inline $AHED; 



Function Declarations 



A function declaration defines a part of the program that computes and returns a 
value. 



function declaration 



function heading -^^T^ function body 



The function heading specifies the identifier for the function, the formal 
parameters (if any), and the function result type. 
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function 



heading — 



function 



>i 



identifier 



formal parameter list 



result type 



result type 



» | type identifier 
string ) 



A function is activated by the evaluation of a function call. The function call 
gives the function's identifier and any actual parameters required by the func- 
tion. A function call appears as an operand in an expression. When the expres- 
sion is evaluated, the function is executed, and the value of the operand becomes 
the value returned by the function. 

The statement part of the function's block specifies the statements to be exe- 
cuted upon activation of the function. The block should contain at least one 
assignment statement that assigns a value to the function identifier. The result of 
the function is the last value assigned. If no such assignment statement exists, or 
if it is not executed, the value returned by the (unction is unspecified. 

If the function's identifier is used in a function call within the function's block, 
the function is executed recursively. 

Following are examples of function declarations: 

function llax(a: Vector; n: Integer): Extended; 
var 

x: Extended; 
i: Integer; 
begin 

X a[l]; 

for i := E to n do if X < aCi] then x := aCi]; 
Max x; 
end; 

function Power(x: Extended; y: Integer): Extended; 
var 

z: Extended; 
i: Integer; 
begin 

z:=l.D;i:=y; 
while 1 > D do 
begin 

if Odd(i) then z := z * x; 
i :- 1 div a; 
X :» Sqr(x); 
end; 

Power := z; 
end; 
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Functions may be declared as forward, external, or inline in the same way as 
procedures are. 



function body 



block 



forward) — 
external)" 



inline body 



Parameters 



The declaration of a procedure or function specifies a formal parameter list. Each 
parameter declared in a formal parameter list is local to the procedure or func- 
tion being declared, and can be referred to by its identifier in the block associ- 
ated with the procedure or function. 



formal parameter list »^(^ * parameter declaration 

G> — 



parameter declaration 



identifier list 



L^^j^-^ parameter type _t 



parameter type 



'-*c 



type identifier 
string ) 
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There are three kinds of parameters: value parameters^ variable parameters, 
and untyped variable parameters. They are characterized as follows: 

• A parameter group without a preceding var and followed by a type is a list of 
value parameters. 

• A parameter group preceded by var and followed by a type is a list of variable 
parameters. 

• A parameter group preceded by var and not followed by a type is a list of 
untyped variable parameters. 

Value Parameters 



A formal value parameter acts like a variable local to the procedure or function, 
except that it gets its initial value from the corresponding actual parameter upon 
activation of the procedure or function. Changes made to a formal value parame- 
ter do not aflFect the value of the actual parameter. 

A value parameter s corresponding actual parameter in a procedure statement 
or function call must be an expression, and its value must not be of file-type or of 
any structured-type that contains a file-type. 

The actual parameter must be assignment compatible with the type of the 
formal value parameter. If the parameter type is string, then the formal parame- 
ter is given a size attribute of 255. 

Variable Parameters 



A variable parameter is employed when a value must be passed from a procedure 
or function to the caller. The corresponding actual parameter in a procedure 
statement or function call must be a variable reference. The formal variable 
parameter represents the actual variable during the activation of the procedure 
or function, so any changes to the value of the formal variable parameter are 
reflected in the actual parameter. 
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Within the procedure or function, any reference to the formal variable param- 
eter accesses the actual parameter itself. The type of the actual parameter must 
be identical to the type of the formal variable parameter (you can bypass this 
restriction through untyped variable parameters). If the formal parameter type is 
string, it is given the length attribute 255, and the actual variable parameter 
must be a string-type with a length attribute of 255. 

File-types can only be passed as variable parameters. 

If referencing an actual variable parameter involves indexing an array or find- 
ing the object of a pointer, these actions are executed before the activation of the 
procedure or function. 

Components of variables of any packed structured type (including components 
of string- type variables) cannot be used as actual variable parameters. 



Untyped Variable Parameters 



When a formal parameter is an untyped variable parameter, the corresponding 
actual parameter may be any variable reference, regardless of its type. 

Within the procedure or function, the untyped variable parameter is typeless; 
that is, it is incompatible with variables of all other types, unless it is given a 
specific type through a variable-type-cast. 

An example of untyped variable parameters: 

function Equal(var source, dest; size: Integer): Boolean; 
type 

Bytes = arrayCD. .Maxlnt] of -1.2fl..l57; 
var 

N: Integer; 
begin 

Equal := true; 

for N := D to size - 1 do 

if Bytes(source)[N] <> Bytes(dest) [N] then Equal := false; 
end; 

The above function may be used to compare any two variables of any size. For 
instance, given the declarations 

type 

Vector = array tl.. ID] of Integer; 
Point = record 

x,y: Integer; 
end; 

var 

VeclrVec5: Vector; 
N: Integer; 
P: Point; 
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then the function calls 

Equal(Vecl,Vec5,Size0f (Vector) ) 
Equal (Vecl/Vec5,Size0f (Integer )«N) 
Equal ( Vec [ 1 ] , Vecl [ b ] , S izeOf ( Integer ) *5 ) 
Equal(Vecl£l],P,<) 

compare Vecl to Vec2, compare the first N components of Vecl to the first N 
components of Vec2, compare the first five components of Vecl to the last five 
components of Vecl, and compare Vecl[l] to P.x and Vecl[2] to P.y. 
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T E R 23 

Programs and Units 



Program Syntax 



A Turbo Pascal program has the form of a procedure declaration except for its 
heading and an optional uses-clause. 



program 



program heading 



uses clause 



rj 



biock 



The Program-Heading 



The program heading specifies the program's name and its program parameters. 



program / s r— — — — 

heading - ^program J — » | identifier 



program parameters 



program parameters 



identifier list 
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The program name is used to determine the default name of the code file in 
which to store the program's code when it is compiled to disk. You may override 
the default code file name with a {$0 {filename)} compiler directive (see Appen- 
dix C, **Compiler Directives"). 

The program-parameters, if present, are purely decorative and are ignored by 
the compiler. 



The Uses-Clause 



The uses-clause identifies all units used by the program, including units that it 
uses directly and units that are used by those units. 



uses clause 




The PasSystem unit is always used automatically. PasSystem implements all 
low-level run-time support routines, such as string handling, set handling, 
dynamic memory allocation, and range checking. 

The PasInOut and PasConsole units are also used automatically (and in that 
order), unless a {$U— } compiler directive appears before the uses-clause. 
PasInOut implements the Standard Input and Output procedures and functions, 
and PasConsole implements Console device. These two units are required when 
writing a textbook Pascal program, but, when writing a Macintosh Application, 
none or only some of them may be required; in that case, a {$U— } compiler 
directive should appear before the uses- clause. 

The {$U (filename)} directive is used to specify the name of a unit library file 
to search in addition to the resident units. Multiple unit library files may be 
specified through multiple {$U (filename)} directives. All {$U (filename)} 
directives must appear before the uses-clause. See Appendix C for further 
details. 



Segmentation 



A Macintosh appfication consists of one or more code segments. Small programs 
are usually contained in a single code segment, but larger programs are divided 
into several segments for two reasons. First, the Macintosh restricts the size of a 
single segment to 32K bytes, which means that a program cannot be larger than 
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32K bytes if it is not segmented. Second, parts of a program that are not exe- 
cuted often (such as initialization and printing) don't have to be kept in memory 
when they aren't being used; instead, they can be in a separate segment that is 
swapped in when needed. 

By default, segmentation is disabled in Turbo Pascal, which means that the 
size of a program cannot exceed 32K bytes. To enable segmentation, place a 
{$S+} compiler directive in the beginning of the program. 

The code of a program's main statement-part is always placed in a segment 
whose name is a string of blanks (the blank segment). When segmentation is en- 
abled, the code of any unit, prcxjeduie, or function may be placed in a different seg- 
ment by using the {$S (SegName)} compiler directive. When a {$S {SegName)} 
directive appears in the uses-clause, the code of the following units are placed in 
the named segment. When a {$S (SegName)} directive appears in the declara- 
tion-part, the code of the following procedures and functions are placed in the 
named segment. If no {$S (SegName)} directives appear in a program, or if seg- 
mentation is not enabled through a {$S+} directive, the code of all units, proce- 
dures, and functions are placed in the blank segment. 

For furdier information about the {$S+}, {$S-}, and {$S (SegName)} com- 
piler directives, see Appendix C. 



Unit Syntax 



Units are the basis of modular programming with Turbo Pascal. They are used to 
create libraries that you can include in various programs without making the 
source code available, and to divide large programs into logically related mod- 
ules. 



unit — ^ unit heading -^7)-^ interface part implementation part initialization part "^^T^ 



The Unit-Heading 



The unit heading specifies the unit's name and its unit number, 
unit number 



sign 



unsigned integer 



unit heading 



itifier -^i)^ 



unit number 
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The unit name is used when referring to the unit in a uses-clause. Further- 
more, it is used to determine the default name of the unit library file in which to 
store the unit when it is compiled to disk. You may override the default library 
file name with a {$0 (filename)} compiler directive (see Appendix C). 

The unit number is a non-zero integer within the range —32768 to 32767. It is 
used internally by the Turbo Pascal compiler to identify symbols from diflFerent 
units, and for that reason it must be unique; that is, no two units may have the 
same unit number if they are to be used in the same compilation. 

Unit numbers —1 to —32 are reserved by Turbo Pascal for the Pascal run-time 
support units and the Macintosh interface units. In general, you should not use 
negative unit numbers, although the compiler will not issue an error message if 
you do. 



The Interface-Part 



The interface-part declares constants, types, variables, procedures, and func- 
tions that are public, that is, available to the host (the program or unit that uses 
the unit). The host can access these entities as if they were declared in a block 
that encloses the host, 
interface part 



Qnterface) - 



uses clause -> 



constant declaration part 



type declaration part 



variable declaration part 



procedure and function heading part — I 



procedure and function 
lieading part 



procedure heading 



^ function heading 



_l -» (external"y -r»( ; 

inline body 



Unless a procedure or function is inline or external, the interface-part only 
lists the procedure or function heading. The block of the procedure or function 
follows in the implementation-part. 
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The Implementation-Part 



The implementation-part defines the block of all public procedures and functions 
(unless they are inline or external). In addition, it declares constants, types, 
variables, procedures, and functions that are private, that is, not available to the 
host. 

rmpiementation part 



implementation ^ 



constant declaration part 



type declaration part 



variable declaration part 



procedure and function declaration part 



procedure and function 
declaration part 



procedure declaration 



function declaration 



In eflFect, the procedure and function declarations in the interface-part are like 
forward declarations, although the forward directive is not specified. Therefore, 
these procedures and functions can be defined and referenced in any sequence 
in the implementation-part. While you repeat the procedure and fimction identi- 
fiers, you don't specify the formal parameter list for procedures and functions in 
the implementation-part. 

The size of a unit's code cannot exceed 32K bytes. Segmentation directives are 
ignored when compifing a unit, but when a unit is used by a program, its entire 
code may be placed in any segment with a {$S {SegName)} compiler directive 
(see ^Segmentation** a few pages back and Appendix C). 



The Initialization-Fart 



The initialization-part is the last part of a unit. It consists either of the reserved 
word end (in which case the unit has no initialization code) or of a statement-part 
to be executed in order to initiahze the unit. 
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initialization part 



-» ^end^ T 

statement part 



The initialization-parts of units used by a program are executed in the same 
order as the units appear in the uses-clause. 



Units that Use Other Units 



The uses-clause in the host must name all units that are used by the host, 
whether they are used directly or indirectly. Consider the following example: 

unit Unitl(l); unit UnitE(5); prograB Host; 

interface interface uses Unitl, UnitE; 

const 0=1; uses Unitl; const a = b; 

iipleientation const b = c; begin 

const d-d; iipleientation end. 

end. end. 

Unit2 uses Unitl, so for Host to use Unit2 it must first name Unitl in its uses- 
clause. Even though Host does not directly reference any identifiers in Unitl, it 
must stiD name Unitl. 

When changes are made in the interface-part of a unit, other units that use the 
unit must be recompiled. However, if changes are only made to the implementa- 
tion-part or the initialization-part, other units that use the unit need not be 
recompiled. Referring to the example above, if the interface-part of Unitl is 
changed (for example, **c = 2'') Unit2 must be recompiled; changing the imple- 
mentation-part (for example, ''d = 1") doesn't require a recompilation of Unit2, 

When a unit is compiled. Turbo Pascal computes a unit version number, which 
is basically a checksum of the interface-part. Referring to the example above, 
when Unit2 is compiled, the current version number of Unitl is saved in the 
compiled version of Unit2. When Host is compiled, the version number of Unitl 
is checked against the version number stored in Unit2. If the version numbers 
do not match, indicating that a change was made in the interface-part of Unitl 
since Unit2 was compiled, the compiler shows an error. 



272 



Turbo Pascal for the Macintosh 



CHAPTER 



Input and Output 



This chapter describes the standard (or built-in) input and output (I/O) proce- 
dures and functions of Turbo Pascal. 

The code for all I/O procedures and functions reside in the PasInOut unit. If 
you are compiling in the {$U-} state and want to use standard I/O, your program 
must name the PasInOut unit in its uses-clause. 



An Introduction to I/O 



A Pascal file variable is any variable whose type is a file-type. There are two 
classes of files: textfiles and typed-files, A file variable declared to be a type 
identical to the standard type text is a textfile. A file variable declared to be a 
type that was defined using the file of construct is a typed-file. 

Before a file variable is used, it must be opened. When a file is opened, the file 
variable is associated with an external file that stores the information written to 
the file or supplies the information read from the file. An external file is typically 
a named disk file, but it may also be a device, such as the keyboard or the 
display. 

An existing file may be opened via the Reset procedure, and a new file may be 
created and opened via the Rewrite procedure. Textfiles opened with Reset are 
read-only and textfiles opened with Rewrite are write-only. Typed-files always 
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allow both reading and writing regardless of whether they were opened with 
Reset or Rewrite. 

The standard file variables Input and Output are opened automatically when 
program execution begins. Input is a read-only file associated with the keyboard 
and Output is a write-only file associated with the display. Note that Input and 
Output are defined by the PasConsole unit. If you are compiling in the {$U— } 
state and want to use the Input and Output files, your program must name the 
PasConsole unit in its uses-clause. 

A file is a linear sequence of components, each of which has the component- 
type of the file. Each component has a component number. The first component 
of a file is considered to be component zero. 

Files are normally accessed sequentially. That is, when a component is read 
using the standard procedure Read or written using the standard procedure 
Write, the current file position moves to the file component that is numerically 
next. However, typed-files may also be accessed randomly visi the standard pro- 
cedure Seek, which moves the current file position to a specified component. 
The standard functions FilePos and FileSize may be used to determine the cur- 
rent file position and the current file size of a typed-file. 

When a program completes processing a file, the file must be closed using the 
standard procedure Close. Closing a file completely updates the external file it 
was associated widi and breaks the link between the file variable and the exter- 
nal file. The file variable can then be associated with another external file. 

By default, all calls to standard I/O procedures and functions are automatically 
checked for errors: If an error occurs, the program terminates displaying the 
System Error dialog box. This automatic checking may be turned on and oflP 
using {$1+} and {$1— } compiler directives. When I/O checking is ofi", i.e., when 
a procedure or function call is compiled in the {$1—} state, an I/O error does not 
cause the program to halt. To check the result of an I/O operation, you must call 
the standard hinction lOResult. 



Standard Procedures and Functions for All FUes 



The Reset Procedure 

Syntax: Reset ( f [ , title [ , bufsize ] ] ) 

Opens an existing file or rewinds an open file. / is a file variable of any file- 
type, title is an optional string-type expression, bufsize is an optional expression 
of type Integer. 
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If title is specified, Reset opens the existing external file with the name title 
and associates/ with this external file. It is an error if there is no existing external 
file of the given name. If/ is a textfile, the call to Reset may optionally specify the 
size of the buflFer to be used when reading from the external file. The default 
bufiPer size is 512 bytes. 

If title is not specified, / must already be open. Reset(f) causes / to be 
^'rewound", that is, the current file position is reset to the beginning of the file. 

If/ is a textfile, / becomes read-only. After a call to Reset, Eof(f) is true if the 
file is empty. Otherwise, Eof(f) is false. 

The Rewrite Procedure 

Syntax: Rewrite ( f [ , title [ , bufsize ] ] ) 

Creates and opens a new file or rewinds and erases an open file. / is a file 
variable of any file-type, title is an optional string-type expression, bufsize is an 
optional expression of type Integer. 

If title is specified, Rewrite creates a new external file with the name title and 
associates /with this external file. If an external file with the same name already 
exists, it is deleted and a new empty file is created in its place. If/ is a textfile, 
the call to Rewrite may optionally specify the size of the buflFer to be used when 
writing to the external file. The default buflFer size is 512 bytes. 

If title is not specified, / must already be open. Rewrite(f) causes / to be 
"rewound", that is, the current file position is reset to the beginning of the file 
and any prior contents off are deleted. 

Iff is a textfile, / becomes torite-only. After a call to Rewrite, Eof(f) is always 
true. 

The Close Procedure 

Syntax: Close (f) 

Closes an open file , /is a file variable of any file-type. The association between 
/ and its external file is broken, and the external file is completely updated and 
then closed. 

The Rename Procedure 

Syntax: Rename ( oldtitle , newtitle ) 

Renames an external file, oldtitle and newtitle are string-type expressions. The 
external file with the name oldtitle is renamed to newtitle. 
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The Erase Procedure 

Syntax: Erase ( title ) 

Erases an external file, title is a string-type expression. The external file with 
the name title is erased. 

The lOResult Function 

Syntax: lOResult 
Result type: Integer 

lOResult returns an integer value that is the status of the last I/O operation 
performed. The codes returned are summarized in Appendix B. A value of zero 
reflects a successful I/O operation. 

Standard Procedures and Functions for Typed^FUes 



The procedures and functions described in this section may only be applied to 
typed-files. Furthermore, a file passed to one of these procedures or functions 
must have been opened using Reset or Rewrite, 

The Read Procedure 

Syntax: Read ( f , vl [ , v2 , . . . , vn ] ) 

Reads a file component into a variable. / is a file variable, and each i; is a 
variable of the same type as the component type of/ For each variable read, the 
current file position is advanced to the next component. It is an error to attempt 
to read from a file when the current file position is at the end of the file, that is, 
when EofJ) is true. 

The Write Procedure 

Syntax: Write ( f , vl [ , v2 , . . . , vn ] ) 

Writes a variable into a file component. / is a file variable, and each t; is a 
variable of the same type as the component type of/ For each variable written, 
the current file position is advanced to the next component. If the current file 
position is at the end of the file, that is, if Eof(f) is true, the file is expanded. 
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The Seek Procedure 

Syntax: Seek ( f , n ) 

Changes the current file position to a specified component, /is a file variable, 
and n is an expression of type Longlnt. The current file position off is moved to 
component number n. The number of the first component of a file is zero. If n is 
greater than the number of the last component in /, the current file position is 
moved to the end of the file, and Eofif) becomes true. 

The Eof Function 

Syntax: Eof(f) 
Result type: Boolean 

Returns the end-of-file status of a file, /is a file variable. Eof(f) returns true if 
the current file position is beyond the last component of the file, or if the file 
contains no components. Otherwise, Eofif) returns false. 

The FilePos Function 

Syntax: FilePos (f) 
Result type: Longlnt 

Returns the current file position of a file, / is a file variable. If the current file 
position is at the beginning of the file, FilePos(f) returns zero. If the current file 
position is at the end of the file, that is, if Eof(f) is true, FilePos(f) is equal to 
FileSize(f). 

The FileSize Function 

Syntax: FileSize ( f ) 
Result type: Longlnt 

Returns the current size of a file. / is a file variable. FileSize(f) returns the 
number of components in/ If the file is empty, FihSize(f) returns zero. 



Standard Procedures and Functions for Texifiles 



This section describes input and output using file variables of the standard type 
text. Note that in Turbo Pascal, the type text is distinct from the type file of 
Char. 
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when a textfile is opened, the external file is interpreted in a special way: It is 
considered to represent a sequence of characters formatted into lines, where 
each line is terminated by an end-of-line character (CR character, ASCII value 
13). 

For textfiles, there are special forms of Read and Write that allow you to read 
and write values that are not of type Char. Such values are automatically trans- 
lated to and from their character representation. For example, Read(fJ) where i 
is an integer-type variable will read a sequence of digits, interpret that sequence 
as a decimal integer, and store it in i. 

As noted previously there are two standard textfile variables, Input and Out- 
put. The standard file variable Input is a read-only file associated with the key- 
board, and the standard file variable Output is a write-only file associated with 
the display. Input and Output are automatically opened when a program begins 
execution. 

All of the standard procedures and functions described in this section need not 
have a file variable explicitly given as a parameter. If the file parameter is omit- 
ted, Input or Output will be assumed by default, depending on whether the 
procedure or function is input-oriented or output-oriented. For instance, 
Read(x) corresponds to Read(Input,x) and Write(x) corresponds to Wnte(Out- 
putyx). 

If you do specify a file when calling one of the procedures or functions in this 
section, the file must have been opened using Reset or Rewrite. It is an error to 
pass a file that was opened with Reset to an output-oriented procedure or fiinc- 
tion. Likewise, it is an error to pass a file that was opened with Rewrite to an 
input-oriented procedure or function. 

The Read Procedure 

Syntax: Read ( [ f , ] vl [ , v2 vn ] ) 

Reads one or more values from a textfile into one or more variables. /, if speci- 
fied, is a textfile variable. Iff is omitted, the standard file variable Input is 
assumed. Each i; is a variable of a char-type, an integer-type, a real-type, or a 
string-type. 

Read with a Char-Type Variable With a char-type variable. Read reads one 
character from the file and assigns that character to the variable. If Eof(f) was 
true before Read was executed, the value Chr(0) is assigned to the variable. If 
Eoln(f) was true, the value Chr(13) is assigned to the variable. The next Read 
will start with the next character in the file. 
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Read with an Integer-Type Variable With an integer-type variable, Read 
expects a sequence of characters that form a signed whole number according to 
the syntax shown (except that hexadecimal notation is allowed). Any blanks, tabs, 
or end-of-line characters preceding the numeric string are skipped. Reading 
ceases at the first blank, tab, or end-of-line character following the numeric 
string or if Eof(f) becomes true. If the numeric string does not conform to the 
expected format, an I/O error occurs. Otherwise, the value is assigned to the 
variable. If Eof(f) was true before Read was executed, or if Eof(f) becomes true 
while skipping blanks, tabs, and end-of-Hne characters, the value zero is 
assigned to the variable. The next Read will start with the blank, tab, or end-of- 
line character that terminated the numeric string. 

Read with a Real-Type Variable With a real-type variable, Read expects a 
sequence of characters that form a signed number according to the syntax shown 
(except that hexadecimal notation is allowed). Any blanks, tabs, or end-of-line 
characters preceding the numeric string are skipped. Reading ceases at the first 
blank, tab, or end-of-line character following the numeric string or if Eof(f) 
becomes true. If the numeric string does not conform to the expected format, an 
I/O error occurs. Otherwise, the value is assigned to the variable. If Eof(f) was 
true before Read was executed, or if Eof(f) becomes true while skipping blanks, 
tabs, and end-of-line characters, the value zero is assigned to the variable. The 
next Read will start with the blank, tab, or end-of-line character that terminated 
the numeric string. 

Read with a String-Type Variable With a string-type variable, Read reads all 
characters up to but not including the next end-of-line character, or until EoJlf) 
becomes true. The resulting character string is assigned to the variable. If the 
resulting string is longer than the maximum length of the string variable, it is 
truncated. The next Read will start with the end-of-Une character that termi- 
nated the string. 

NOTE: Read with a string- type variable does not skip to the next line after 
reading. For this reason, you cannot use successive Read calls to read a sequence 
of strings, as you will never get past the first line — after the first Read, each 
subsequent Read will see the end-of-line character and return a zero-length 
string. Instead, use multiple ReadLn calls to read successive string values. 

The ReadLn Procedure 

Syntax: ReadLn ( [ f , ] vl [ , y2 vn ] ) or ReadLn [(f)] 

The ReadLn procedure is an extension to the Read procedure. After doing the 
same as Read for the parameter list, it skips to the beginning of the next line of 
the file. ReadLn(f) with no parameters causes the current file position to advance 
to the beginning of the next line (if there is one, else to the end of the file). 
ReadLn with no parameter list altogether corresponds to ReadLn(Input), 
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The Write Procedure 

Syntax: Write ( [ f , ] pi [ , p2 pn ] ) 

Writes one or more values to a textfile. /, if specified, is a textfile variable. If/ 
is omitted, the standard file variable Output is assumed. Each p is a write- 
parameter. Each write-parameter includes an output-expression, whose value is 
to be written to the file. As explained below, a write-parameter may also contain 
the specifications of a field-width and a number of decimal places. Each output- 
expression must be of a char-type, an integer-type, a real-type, a string-type, a 
packed-string-type, or a boolean-type. 

Write Parameters A write-parameter has the form 

OutExpr [ : MinWidth E : DecPlaces ] 3 

where OutExpr is an output-expression. MinWidth and DecPlaces are integer- 
type expressions. 

MinWidth specifies the minimum field width. MinWidth must be greater than 
zero. Exactly MinWidth characters are written (using leading blanks if neces- 
sary), except when OutExpr has a value that must be represented in more than 
MinWidth characters; in that case, enough characters are written to represent 
the value of OutExpr. Likewise, if MinWidth is omitted, then enough characters 
as necessary are written to represent the value of OutExpr. 

DecPlaces specifies the number of decimal places in a fixed-point representa- 
tion of a real-type value. It can be specified only if OutExpr is of a real-type, and 
if MinWidth is also specified. If specified, it must be greater than or equal to 
zero. 

Write with a Char-Type Value If MinWidth is omitted, the character value of 
OutExpr is written to the file. Otherwise, MinWidth-1 blanks followed by the 
character value of OutExpr is written. 

Write with an Integer-Type Value If MinWidth is omitted, the decimal repre- 
sentation of OutExpr is written to the file with no preceding blanks. If MinWidth 
is specified, and its value is larger than the length of the decimal string, enough 
blanks are written before the decimal string to make the field width MinWidth. 

Write with a Real-Type Value If OutExpr has a real-type value, its decimal 
representation is written to the file. The format of the representation depends on 

the presence or absence of DecPlaces. 

If DecPlaces is omitted, sl floating-point decimal string is written. If MinWidth 
is also omitted, a default MinWidth of 10 is assumed; otherwise, if MinWidth is 
outside the range 10.. 80, it is truncated to be within that range. The format of 
the decimal string is 

C ! - ] <digit> . <deci-iiials> e [ + S - ] <exponent> 
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These are the components of the output string: 




or **— " according to the sign of OutExpr, 
Single digit, *'0'* only if OutExpr is 0. 
Digit string of MinWidth-9 digits. 
Lowercase "e" character. 

or according to sign of exponent. 
Exponent with trailing blanks to make its width 4. 



If DecPlaces is present, r fixed-point decimal string is written. The format of 
the string is 

[ <blanks> ] C - ] <digits> t . <decinials> ] 
These are the components of the string: 



If DecPlaces is present, and OutExpr is greater than or equal to 10 ^ (19 — 
DecPlaces), the number is formatted in floating-point style with 19 significant 
digits, and written with enough leading blanks to make the field width 
MinWidth, 

Write with a String-Type Value If MinWidth is omitted, the string value of 
OutExpr is written to the file with no leading blanks. If MinWidth is specified, 
and its value is larger than the length of OutExpr, enough blanks are written 
before the decimal string to make the field width MinWidth, 

Write with a Packed-String-Type Value If OutExpr is of a packed-string-type, 
the effect is the same as writing a string whose length is the number of elements 
in the packed-string- type. 

Write with a Boolean Value If OutExpr is of type Boolean, the effect is the 
same as writing the strings 'TRUE' or 'FALSE' depending on the value of Out- 
Expr, 

The WriteLn Procedure 

Syntax: WriteLn ( [ f , ] pi [ p2 pn ] ) or WriteLn [(f)] 

The WriteLn procedure is an extension to the Write procedure. After doing 
the same as Write for the parameter list, it writes an end-of-line character to the 
file. WriteLn(f) with no parameters writes an end-of-fine character to the file. 
WriteLn with no parameter list altogether corresponds to WriteLn(Output), 
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[ (blanks) ] 

[-] 

(digits) 

[ . (decimals) ] 



At least one digit, but no leading zeros. 
Decimals if DecPlaces ) 0. 



Blanks to satisly MinWidth. 
if OutExpr is negative. 



The Eof Function 



Syntax: Eof[(f)] 
Result type: Boolean 

Returns the end-of-file status of a file. /, if specified, is a textfile variable. If/ is 
omitted, the standard file variable Input is assumed. Eof(f) returns True if the 
current file position is beyond the last character of the file, or if the file contains 
no components. Otherwise, Eofif) returns False, 

The Eoln Function 

Syntax: Eoln [(f)] 
Result type: Boolean 

Returns the end-of-line status of a file. / if specified, is a textfile variable. If/is 
omitted, the standard file variable Input is assumed. Eoln(f) returns True if the 
character at the current file position is an end-of-line character or if Eoj(f) is 
true. Otherwise, Eoln(f) returns Fahe, 

The SeekEof Function 

Syntax: SeekEof[(f)] 

Returns the end-of-file status of a file. SeekEof corresponds to Eof, except that 
it skips all blanks, tabs, and end-of-line characters before returning the end-of- 
file status. This is useful when reading numeric values from a textfile. 

The SeekEoln Function 

Syntax: SeekEoln [( f ) ] 

Returns the end-of-line status of a file. SeekEoln corresponds to Eoln, except 
that it skips all blanks and tabs before returning the end-of-line status. This is 
useful when reading numeric values fh)m a textfile. 

Disk FUes 



A file variable is associated with a disk file by specifying the pathname of the disk 
file in a call to Re^ef or Rewrite. A file variable must be associated with an ex- 
ternal file before it can be used; otherwise Turbo Pascal wouldn't know where to 
store the information written to the file or where to retrieve the information read 
from the file. 
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Pathnames 



The Macintosh File Manager uses a pathname to identify a specific file on a 
specific volume. A pathname consists of a file name optionally preceded by a 
volume name and a colon, for instance: 

MyVoluine:MyFile 

On systems with the Hierarchical File Manager, a pathname may optionally 
specify one or more directory names, for instance: 

My Volume : MyDirl : . . . : MyDirn : MyFile 

If a pathname passed to one of the standard I/O procedures does not include a 
volume and directory specification, the file is assumed to reside in the default 
directory on the default volume. 

The Macintosh File Manager also allows a file to be specified through a volume 
reference number and a filename. Basically, a volume reference number identi- 
fies a specific volume or a specific directory on a specific volume. To make a 
standard I/O procedure operate on a file with a given volume reference number, 
call the SetVol routine in the OSIntf unit to set the default volume before calling 
the standard I/O procedure. 

More information on volumes, directories and files can be found in the ''File 
Manager" chapter of Inside Macintosh. 

File Types and Creators 



The Macintosh File System requires that you assign Sifile type and file creator to 
each new file. The file type determines the type of the file, such as text or 
application The file creator identifies the application that created the file; this is 
used in determining which application to launch when the file's icon is double- 
clicked. 

Turbo Pascal determines the file type and file creator of each new file created 
by the Rewrite procedure using four standard variables, which are declared as: 

var 

FileType, FileCreator, 

TextType, TextCreator: packed array[1..4] of Char; 
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The FileType and FileCreator variables determine the type and creator of 
typed-files. The TextType and Ti^itfCr^ator variables determine the type and cre- 
ator of textfiles. The default values are: 



FileType := 'BINfl'; 

FileCreator := 'TPAS' ; 

TextType := 'TEXT'; 

TextCreator := 'TPAS'; 

You may change these defaults by assigning new values to the standard vari- 
ables before cdlling Rewrite, 

More information on file types and creators can be found in the **Finder Inter- 
face" chapter of Inside Macintosh, 

Devices in Turbo Pascal 



In Turbo Pascal, external hardware, such as the keyboard, the display, and the 
printer, are regarded as a devices. A device is treated as a textfile, and it is 
identified through a device name. To associate a device with a textfile variable, 
the device name is passed as the title parameter in a call to Reset or Rewrite, 

Turbo Pascal defines two standard devices: A Console device, which is used to 
communicate with the keyboard and the display, and a Printer device, which is 
used to communicate with the printer. Their device names are 

Console device 'Console:' 
Printer device 'Printer:' 

Turbo Pascal also allows you to define your own devices. 
The Console Device 



The Console device is used to communicate with the keyboard and the display. 

Its device name is 'Console:'. 

The Console device is implemented by the PasConsoIe unit. The PasConsole 
unit furthermore defines the standard file variables Input and Output and associ- 
ates these files with the Console device. If you are compiling in the {$U-} state 
and want to use the Console device, your program must name the PasConsole 
unit in its uses-clause. 
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Using the PasConsole unit in a program may be compared to including the 
declaration 

var 

Input, Output: Text; 
and executing the following procedure calls at the beginning of the program: 

Reset(Input, 'Console:'); 
Rewrite(Output, 'Console:'); 

PasConsole also takes care of initializing all Macintosh ROM Managers, and 
brings up the Console Window, which emulates an 80-character X 25-line ter- 
minal. 

The Console device is line oriented. When reading from the standard file 
Input or a textfile that is associated with the Console device, lines are read one at 
a time and stored in a line buflFer. The Read and ReadLn procedures obtain their 
input from this line buffer. Whenever the line buffer becomes empty, typically 
due to a ReadLn, a new line is input at the next Read or ReadLn. 

The following editing keys are available when inputting lines: 



Typing has the effect of generating an end-of-file status for the file being 
read. Eoj(f) becomes true and stays true until Reset(f) is executed. 

The Printer Device 



The Printer device is used to communicate with the printer. Its device name is 
'Printer:'. 

The Printer device is implemented by the PasPrinter unit. The PasPrinter 
unit furthermore defines a textfile variable called Printer and associates it with 
the Printer device. If you want to use the Printer device, your program must 
name the PasPrinter unit in its uses-clause. 

Using the PasPrinter unit in a program may be compared to including the 
declaration: 



Backspaces one character 
Clears the entire input line 
Terminates the input line 
Generates end-of-file status 



iwi or fiiinn 

no 



var 



Printer: Text; 
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and executing the following procedure call at the beginning of the program: 
Rewrite (Printer, 'Printer:'); 

The Printer device uses text streaming when sending data to the printer. Basi- 
cally this means that the characters are sent directly to the printer with no inter- 
pretation. 

More information on printing can be found in the Trinter Driver" chapter of 
Inside Macintosh, 
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CHAPTER 



Standard Procedures and Functions 



This chapter describes all the standard (built-in) procedures and functions in 
Turbo Pascal, except for the I/O procedures and functions discussed in Chapter 
23. 

Standard procedures and functions are predeclared. Since all predeclared 
entities act as if they were declared in a block surrounding the program, no 
conflict arises from a declaration that redefines the same identifier within the 
program. 

Exit and Halt Procedures 



The Exit Procedure 

Syntax: Exit 

Exits immediately from the current block. When Exit is executed in a subrou- 
tine, it causes the subroutine to return. When it is executed in the statement- 
part of a program, it causes the program to terminate. A call to Exit may be 
compared to a goto-statement addressing a label just before the end of a block. 
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The Halt Procedure 



Syntax: Halt 

Immediately stops execution of the program. A call to Halt corresponds to a 
call to the ExitToShell routine in the Macintosh operating system. 

Dynamic AUocatwn Procedures and Functions 



These procedures and functions are used to manage the heap, a memory area 
that is unallocated when a program begins execution. The dynamic allocation 
procedures and functions operate on the Application Heap, and the routines are 
implemented using the Macintosh Memory Manager. 

The New Procedure 
Syntax: New ( p ) 

Creates a new dynamic variable and sets a pointer variable to point to it. p is a 
pointer variable of any pointer-type. The size of the allocated memory block 
corresponds to the size of the type that p points to. The memory block is allo- 
cated through a call to the NewPtr routine of the Macintosh Memory Manager. 
The newly created variable can be referenced as p^. If there isn't enough free 
space in the heap to allocate the new variable, p is set to nil. 

The Dispose Procedure 

Syntax: Dispose ( p ) 

Disposes a dynamic variable, p is a pointer variable of any pointer-type that 
was previously assigned by the New procedure or was assigned a meaningful 
value by an assignment statement. Dispose destroys the variable referenced by p 
and returns its memory region to the heap. It does so by calling the DisposPtr 
routine of the Macintosh Memory Manager. The value of p then becomes unde- 
fined, and it is an error to subsequently reference p^. 
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The MemAvail Function 

Syntax: MemAvail 
Result type: Longint 

Returns the number of free bytes of heap storage available. This number is 
calculated from the free size of the heap plus the size by which the heap may 
grow. Note that a block of storage the size of the returned value is unlikely to be 
available due to fragmentation of the heap. To find the largest free block, call 
MaxAvail. 

The MaxAvail Function 

Syntax: MaxAvail 
Result type: Longint 

Returns the size of the largest contiguous free block in the heap. MaxAvail 
expands the heap to its maximum limit and then compacts the heap. This corre- 
sponds to a call to the Memory Manager s MaxApplZone routine, followed by a 
call to the CompactMem routine. 

Transfer Functions 



The procedures Pack and Unpacky as defined in Standard Pascal, are not imple- 
mented by Turbo Pascal. 

The Chr Function 

Syntax: Chr ( x ) 
Result type: Char 

Returns a character with a specified ordinal number, x is an integer-type 
expression. The result is the character whose ASCII value is x. 

The Ord Function 

Syntax: Ord ( x ) 

Result type: Integer or Longint 

Returns the ordinal number of an ordinal- type or pointer-type value. If x is an 
ordinal-type expression, the result is of type Integer and the value is the 
ordinality of x. If x is a pointer-type expression, the result is of type Longint, and 
the value is the address of the dynamic variable pointed to by x. 
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The Ord4 Function 



Syntax: Ord4 ( x ) 
Result type: Longlnt 

Returns the ordinal number of an ordinal-type or pointer-type value. Ord4 
corresponds to Ord, except that the type of the result is always Longlnt, 

The Pointer Function 

Syntax: Pointer ( x ) 
Result type: Pointer 

Converts an integer- type or pointer-type value to a pointer-type value. If x is 
an integer-type expression, Pointer returns a pointer value that points to the 
address given by x. If x is a pointer-type expression, Pointer returns a pointer to 
the same location. The type of the result is the same nil, that is, it is assignment 
compatible with any pointer-type. 

The Trunc Function 

Syntax: Trunc ( x ) 
Result type: Lor^nt 

Truncates a real-type value to an integer-type value, x is a real-type expres- 
sion. Trunc returns a Lon^nt value that is the value of x rounded towards zero. 

The Round Function 

Syntax: Round ( x ) 
Result type: Longlnt 

Rounds a real-type value to an integer-type value, x is a real-type expression. 
Round returns a Longlnt value that is the value of x rounded to the nearest whole 
number. If x is exactly halfway between two whole numbers, the result is the 
number with the greatest absolute magnitude. 

The Float Function 

Syntax: Float ( x ) 
Result type: Re(d 

Converts an integer- type value to a real- type value, x is an integer- type 
expression. Note that the compiler automatically converts integer-type values to 
real-type values when they appear in real-type expressions. You need not use 
Float unless you want to explicitly force this conversion. 
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Arithmetic Functions 



The Abs Function 

Syntax: Abs ( x ) 

Result type: Same type as parameter 

Returns the absolute value of the argument, x is an integer-type or real-type 
expression. The result, of the same type as x, is the absolute value of x. 

The Sqr Function 

Syntax: Sqr ( x ) 

Result type: Same type as parameter 

Returns the square of the argument, x is an integer-type or real-type expres- 
sion. The result, of the same type as x, is the square of x, i.e., x * x. 

The Int Function 

Syntax: Int ( x ) 
Result type: Real 

Returns the integer part of the argument, x is a real-type expression. The 
result is the integer part of x, i.e., x rounded towards zero. 

The Sqrt Function 

Syntax: Sqrt ( x ) 
Result type: Real 

Returns the square root of the argument, x is a real-type expression. The 
result is the square root of x. 

The Sin Function 

Syntax: Sin ( x ) 
Result type: Real 

Returns the sine of the argument, x is a real-type expression. The result is the 
sine of x. x is assumed to represent an angle in radians. 
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The Cos Function 



Syntax: Cos ( x ) 
Result type: Real 

Returns the cosine of the argument, x is a real-type expression. The result is 
the cosine of x. x is assumed to represent an angle in radians. 

The Exp Function 

Syntax: Exp ( x ) 
Result type: Real 

Returns the exponential the argument, jc is a real-type expression. The result 
is the exponential of x, i.e., the value e raised to the power of x, where e is the 
hase of the natural logarithm. 

The Ln Function 

Syntax: Ln ( x ) 
Result type: Real 

Returns the natural logarithm of the argument, x is z real-type expression. 
The result is the natural logarithm of x. 

The ArcTan Function 

Syntax: ArcTan ( x ) 
Result type: Real 

Returns the arctangent of the argument, x is a real-type expression. The result 
is the principal value, in radians, of the arctangent of x. 

Ordinal Functions 



The Succ Function 

Syntax: Succ ( x ) 

Result type: Same type as parameter 

Returns the successor of the argument, x is an ordinal-type expression. The 
result, of the same type as x, is the successor of x. 
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The Fred Function 



Syntax: Pred ( x ) 

Result type: Same type as parameter 

Returns the predecessor of the argument, x is an ordinal-type expression. The 
result, of the same type as x, is the predecessor of x. 

The Odd Function 

Syntax: Odd ( x ) 
Result type: Boolean 

Tests if the argument is an odd number, x is an integer-type expression. The 
result is true if x is an odd number, and/ake if x is an even number. 

String Procedures and Functions 



The Length Function 

Syntax: Length ( s ) 
Result type: Integer 

Returns the dynamic length of a string. 5 is a string-type expression. The 
result is the length of s. 

The Pos Function 

Syntax: Pos ( substr , s ) 
Result type: Integer 

Searches for a substring in a string, substr and s are string-type expressions. 
Pos searches for substr within s, and returns an Integer value that is the index of 
the first character of substr within s. If substr is not found, Pos returns zero. 

The Concat Function 

Syntax: Concat ( si [ , s2 sn ] ) 
Result type: String 

Concatenates a sequence of strings. Each parameter is a string-type expres- 
sion. The result is the concatenation of all the string parameters. If the resulting 
string is longer than 255 characters, it is truncated after the 255th character. 
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The Copy Function 



Syntax: Copy ( s , index , count ) 
Result type: String 

Returns a substring of a string. ^ is a string-type expression, index and count 
are integer-type expressions. Copy returns a string containing count characters 
starting with the indexth character in s. If index is larger than the length of s, an 
empty string is returned. If count specifies more characters than remain starting 
at the indexth position, only the remainder of the string is returned. 

The Delete Procedure 

Syntax: Delete ( s , index , count ) 

Deletes a substring from a string, s is a string-type variable, index and count 
are integer-type expressions. Delete deletes count characters from s starting at 
the indexth position. If index is larger than the length of s, no characters are 
deleted. If count specifies more characters than remain starting at the intfexth 
position, the remainder of the string is deleted. 

The Insert Procedure 

Syntax: Insert ( source , s , index ) 

Inserts a substring into a string, source is a string-type expression. 5 is a string- 
type variable, index is an integer- type expression. Insert inserts source into s at 
the indexth position. If the resulting string is longer than 255 characters, it is 
truncated after the 255th character. 



Console Handling Procedures and Functions 



The routines described in this section reside in the PasConsole unit. Thus, if you 
are compiling in the {$U— } state, your program must name the PasConsole unit 
in its uses-clause. 

The ClearScreen Procedure 

Syntax: ClearScreen 
Clears the screen and places the cursor in the upper left-hand corner. 
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The CkarEOL Procedure 
Syntax: ClearEOL 

Clears all characters from the cursor position to the end of the line without 
moving the cursor. 

The DeleteLine Procedure 

Syntax: DeleteLine 

Deletes the line containing the cursor and moves all lines below it one line up. 

The InsertLine Procedure 
Syntax: InsertLine 

Inserts an empty line at the cursor position. All lines below the are moved one 
line down, and the bottom line scrolls off the screen. 

The GotoXY Procedure 

Syntax: GotoXY ( x , y ) 

Moves the cursor to the position on the screen specified by the Integer expres- 
sions X (horizontal position) and y (vertical position). The upper left corner is 
(1,1). If X is outside the range 1..80 or iiy is outside the range 1..25, the cursor 
does not move. 

The KeyPressed Function 

Syntax: KeyPressed 
Result type: Boolean 

Returns True if a key has been pressed on the keyboard, and False if no key 
has been pressed. 

The ReadChar Function 

Syntax: ReadChar 
Result type: Char 

Causes the cursor to blink while waiting for a key to be pressed. When that 
happens, the character is returned. The character is not echoed on the screen. 
The Command key (1^) functions as the Control key on a standard keyboard: If 
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a key is pressed while the Command key is held down, ReadChar returns the 
control-value of the key, that is, Chr(l) for Q Sl» Chr(2) for dj, and so on. 

MisceUaneom Procedures and Functions 



The SizeOf Function 

Syntax: SizeOf ( x ) 
Result type: Integer 

Returns the number of bytes occupied by the argument, x is either a variable- 
identifier or a type-identifier. SizeOf returns the number of bytes of memory 
occupied by x. 

The MoveLeft Procedure 

Sj^tax: MoveLeft ( source , dest , count ) 

Copies a specified number of contiguous bytes from a source range to a desti- 
nation range (starting at the lowest address), source and dest are variable refer- 
ences of any type, count is an integer-type expression. MoveLeft copies a block of 
count bytes from source to dest, starting with the first byte occupied by source. 
When source and dest overlap, you should use this procedure if source is at the 
higher address. No checking whatsoever is performed, so be careful with this 
procedure. 

The MoveRight Procedure 

Syntax: MoveRight ( source , dest , count ) 

Copies a specified number of contiguous bytes from a source range to a desti- 
nation range (starting at the highest address), source and dest are variable refer- 
ences of any type, count is an integer-type expression. MoveRight copies a block 
of count bytes from source to dest, starting with the last byte occupied by source. 
If source and dest overlap and dest is at the higher address, you should use this 
procedure. No checking whatsoever is performed, so be careful. 
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The FillChar Procedure 

Syntax: FillChar ( x , count , ch ) 

Fills a specified number of contiguous bytes with a specified value, x is a 
variable reference of any type, count is an integer-type expression, ch is an 
ordinal-type expression. FillChar writes the value of ch into count contiguous 
bytes of memory starting at the first byte occupied by x. No checking whatsoever 
is performed, so be careful. 

The ScanEQ Function 

Syntax: ScanEQ ( limit , ch , x ) 
Result type: Integer 

Scans a range of bytes for the first occurrence of a given value, limit is an 
integer-type expression, ch is an ordinsJ-type expression, x is a variable refer- 
ence of any type. ScanEQ scans x, looking for the first occurrence of the byte 
value given by ch. The scan begins with the first byte in x. If ch is not found 
within Kmf* characters from the beginning of x, the value returned is equal to 
limit. Otherwise, the value returned is the number of bytes scanned before ch 
was found. 

The ScanNE Function 

Syntax: ScanNE ( limit , ch , x ) 
Result type: Integer 

ScanNE does the same as ScanEQ, except that it searches for a byte value that 
does not match the ch parameter 

The Hi Function 

Syntax: Hi ( x ) 

Result type: -128 .. 127 

Returns the high-order byte of the argument, x is an expression of type 
Integer, Hi returns the high-order byte of oc as a signed value. 
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The Lo Function 

Syntax: Lo ( x ) 

Result type: -128 .. 127 

Returns the low-order byte of the argument, x is an expression of type Integer, 
Lo returns the low-order byte of x as a signed value. 

The Swap Function 

Syntax: Swap ( x ) 
Result type: Integer 

Swaps the high- and low-order bytes of the argument, x is an expression of 
type Integer, 

The HiWord Function 

Syntax: HiWord ( x ) 
Result type: Integer 

Returns the high-order word of the argument, x is an expression of type 
Longlnt, HiWord returns the high-order word of x as a signed value. 

The LoWord Function 

Syntax: LoWord ( x ) 
Result type: Integer 

Returns the low-order word of the argument, x is an expression of type 
Longlnt, HiWord returns the low-order word of :t as a signed value. 

The SwapWord Function 

Syntax: SwapWord ( x ) 
Result type: Longlnt 

Swaps the high- and low-order words of the argument, x is an expression of 
type Longlnt, 
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CHAPTER 



The Standard Apple Numeric Environment 

(SANE) Library 



This chapter discusses the features and uses of the Standard Apple Numeric 
Environment (SANE) and the routines contained in the SANE library. You'll 
learn about the data types provided by SANE. You'll also delve into each of the 
types, procedures, and functions contained in the SANE library. 

SANE's main features are based on a standard proposed by the Institute of 
Electrical and Electronics Engineers (IEEE's Standard 754 for Binary Floating- 
Point Arithmetic). This standard specifies standardized data types, arithmetic, 
and conversions. 

All floating-point mathematical calculations performed by Turbo Pascal use 
SANE's standards. This means uniform floating-point operations, which return 
the most accurate results. 

To surpass real-type precision, SANE ofiers floating-point type extensions. 
The SANE library provides numerical functions beyond those in Standard Pascal 
and routines to control the environment for floating-point calculations. 
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The SANE Data Types 



SANE provides three application data types (Single, Double, and Comp) and an 
arithmetic type (Extended). The original specification for Pascal had one data 
type for use with floating-point numbers, the Real type. Turbo Pascal oflFers — in 
addition to the Real type — ^the Single, Double, Extended, and Com^ types. 
Extended alludes to the extended precision with which Turbo Pascal performs all 
arithmetic operations. Values that can be represented as any of the first three 
types can be represented also in Extended. Turbo Pascal's Real type is identical 
to SANE's Single type. 

The Single type is the smallest format you can use with floating-point num- 
bers. It uses 32 bits of memory. 

The Double type uses 64 bits for storage. 

The Extended type uses an 80-bit format. Any arithmetic involving real-type 
values is performed with the Extended type. 

The Comp type stores integral values in 64 bits. It is considered a real-type 
because arithmetic done with operands of type Comp uses the Extended type. 

Choosing a Data Type 



Four factors to consider when selecting a data type are format (fixed or floating- 
point), precision, range, and memory usage. 

The precision, range, and memory usage for each SANE data type are shown 
in Table 26-1. 
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Table 26-1 SANE Data Types 



Type Identifier 


Single 


Double 


Comp 


Extended 


Size (bytes:bits) 


4:32 


8:64 


8:64 


10:80 


Binary exponent 










range 










Minimum 


-126 


-1022 


— 


-16383 


Maximum 


127 


1023 




16384 y 


Significand precision 










Bits 


24 


53 


63 


64 


Decimal digits 


7-8 


15-16 


ia-19 


19-20 












(approximate) 










Min negative 


-3.4E+38 


-1.7E+308 


«-9.2E18 


-LIE +4932 


Max neg norm 


-1.2E-38 


-2.3E^08 




1.7E^932 


Max neg denorm 


-1.5E-45 


-5.0E-324 




-1.9E-4951 


Min pes norm 


1.2E-38 


2.3E-308 




1.7E-4932 


Min pos denorm 


-1.5E-45 


-5.0E-324 




-1.9E-4951 


Max positive 


3.4E+38 


L7E+308 


'«9.2E18 


LlE+4932 


Infinities 


Yes 


Yes 


No 


Yes 


NaNs 


Yes 


Yes 


Yes 


Yes 



Many programs require a counting type that counts things exactly. The SANE 
type Comp can be used for this purpose, for instance by representing monetary 
values as integral numbers of cents or mils (thousands). The sum, diflFerence, or 
product of any two Comp values can be calculated exactly if the magnitude of the 
result does not exceed 2^"' (9,223,372,036,854,775,807). Comp values can be 
combined with extended values in floating-point computations (such as calculat- 
ing compound interest). 

Arithmetic with Comp type variables, like all SANE arithmetic, is performed 
internally using the Extended type. Precision is not affected, as conversion from 
Comp to Extended is always exact. 

Values Represented 



The floating-point types {Single, Double, and Extended) store binary representa- 
tions of a sign (H- or — ), an exponent, and a significand. A represented number 
has the value 

. J- . -, -.exponent 

± Significand * 5 

where the significand has a single bit to the left of the binary point (that is, 0 ^ 
significand ( 2). 
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Range and Precision 



Table 26-1 shows the range and precision of the real-types supported by SANE 
and Turbo Pascal. Decimal ranges are shown as chopped two-digit decimal rep- 
resentations of the exact binary values. 

Using the Single type, the largest representable number is: 

signif icand =2-2^"^ 
= 1.U 

exponent = 127 



= Limuummimmii, 



value = (2 - 2"^) * 2^' 



« 3.403 * 10"" 



The smallest representable positive normalized number is: 



= LOOOOOOOOOOOOOOOOOOOOOOO^ 



signif icand = 1 
= 1 

exponent = -126 

value = 1 * 2 ''' 

« 1.175 * lO "" 

The smallest representable positive denormalized number is: 

signif icand = 2'^^ 

= O.OOOOOOOOOOOOOOOOOOOOOOl^ 

exponent = -126 

value = 2'' * 2-''' 

« 1.401 * 10^ 



Formats 



Following are the formats of the four SANE real-types, showing the fields that 
each type divides a number into. 

The Single Type 

A 32-bit Singfe number is divided into three fields: 

1 fl aa widths 

m e 

! ! . 

ntsb Isb msb Isb order 



f I 
I 
I 
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NOTE: msb means most significant bit and bb means least significant bit. 

The value v of the number is determined by these fields: 

If D < e < 555, then v = (-1)^ * ^^^'.IV^ * (l-f)- 

If e = D and f y D, then v = (-1)^ ♦ a^^ ^ » (D.f). 

If e = D and f ^ D, then v = (-1)^ • D. 

If e = 255 and f = 0, then v = (-1)^ * oo. 

If e = 555 and f i U, then v is a NaN. 



The Double Type 

A 64-bit Double number is divided into three fields: 

1 11 5E widths 

!"s~i e \ f \ 

I I I I 

msb Isb msb Isb order 

The value v of the number is determined by these fields: 

If D < e < eD<7, then v » (-1)^ * eJ^'J;""^ • (l.f). 

If e « D and f y 0, then v - (-1)^ » ^^-^^ ) * (D.f). 

If e = D and f = D, then v = (-1)^ » Q. 

If e = 20^7 and f = D, then v = (-1)'' « ». 

If e « 20^7 and f y D, then v is a NaN. 



The Comp Type 

A 64-bit Camp number is divided into two fields: 

1 b3 widths 

ri'T d I 
I I S 

isb Isb msb Isb order 

The value v of the number is determined by these fields: 

If s = 1 and d * D/ then v is the unique Comp KaN. 

Otherwise, v is the two's-coipleroent value 

of the tj4-bit representation. 



The Extended Type 



An 80-bit Extended format number is divided into four fields: 
1 15 1 L3 widths 

j~s~T e TTT f I 
II II i 
I I I I 1 

msb Isb msb Isb order 
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The value v of the number is determined by these fields: 
If D <= e < 3E7t7, then v = (-1)^ ♦ g(e-ib3fl3) ^ (i.f). 

If e = 35?ti? and f = Q, then v = (-1) * *r regardless of i. 
If e = 357b7 and t ¥ U, then v is a NaN, regardless of i. 



The SANE Engine 



This section describes the features of SANE and the interface between the 
SANE engine and Turbo Pascal. 



Extended Arithmetic 



The Extended type is the basis of all arithmetic computation. With Extended 
results, computations are accurate to a precision of 19 decimal digits through a 
range of 10"'^ to 

Turbo Pascal uses the Extended format to store all non-integer numeric con- 
stants and evaluates all non-integer numeric expressions to Extended. The entire 
right side of the following assignment, for instance, will be computed in 
Extended before being converted to the type of the left side: 

var 

X/A/B,C: Real; 
begin 

X (B + Sqrt(B ♦ B - A » C)) / A; 
end 

With no special effort by the programmer. Turbo Pascal does computations 
using the precision and range of the Extended type. The added precision means 
smaller roundoff errors, and the additional range means overflow and underflow 
are less common, so that programs work more often. 

You can go beyond Pascal's automatic Extended capabilities. For example, you 
can declare variables used for intermediate results to be of type Extended. The 
following example computes a sum of products: 

var 

Sum: Real; 

X,Y: array[l. .IDD] of Real; 
I: Integer; 

T: Extended; { for intermediate results } 

begin 

T := D.D; 

for I 1 to IDQ do T := T + XCI] » YCI]; 
Sura T; 
end 
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Had T been declared Real, the assignment to T would have caused a roundoflF 
error at the limit of single precision at each loop entry. But T being Extended, all 
roundoflF errors are at the limit of Extended precision, except for the one resulting 
from the assignment of T to Sum, Fewer roundoflF errors mean more accurate 
results. 

You can also declare formal value parameters and function results to be of type 
Extended to avoid unnecessary conversions between numeric types, which may 
result in loss of accuracy. For example: 

function Area (radius: Extended): Extended; 
begin 

Area := pi » radius » radius; 
end; 

Although the Extended type makes programs less sensitive to certain errors, 
exceptional cases do arise. For example, if all variables in the example below are 
of type Real: 

Average := Sum / Count; Area := Side * Side; + 

what happens if Count is zero or if the product Side * Side is too large to be 
represented in the Real format? Ordinarily, your program stops, displaying an 
error message. However, this is not the only way Turbo Pascal can treat such 
errors. Instead, Turbo Pascal can assign special values to Average and Area, so 
your program can continue. In fact, the IEEE standard refers to ^exceptions'* 
rather than "errors,'' and it specifies "no halts** as the default mode of operation 
for its arithmetic. To install the IEEE defaults, use this statement: 

SetEnvironnient{D) ; 

The SANE library also contains functions and procedures for determining 
when exceptional cases occur. 

Number Classes 



There are five classes of representations in the SANE data formats. 

• Normalized numbers Binary floating-point numbers with a leading signi- 
ficand bit of 1. 

• Zero +0 and -0. 

• Infinities Special bit patterns resulting when floating-point operations attempt 
to produce numbers beyond the largest representable number of the intended 
format. 

• NaNs A bit pattern resulting when a meaningful result cannot be produced by 
a floating-point operation. 
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• Denormalized numbers Non-zero binary floating-point numbers whose sig- 
nificands have leading bits of zero and whose exponents are the minimum 
exponents for the number s storage type. 

Infinities 

Infinities are special SANE representations that can arise in two ways from oper- 
ations on finite values: 

• When an operation should produce an exact mathematical infinity (such as 
1/0), the result is an infinity. 

• When an operation produces a number with magnitude too large for the 
intended floating-point format, the result may (depending on the current 
rounding direction) be an infinity. 

Turbo Pascal predefines a constant, Inf, to have the value positive infinity. Inf 
also represents infinity for input and output of floating-point values. Infinities act 
like mathematical infinities, for example, 1—Inf = —Inf. 

Here's an example of the use of infinity values: 

prograi Useinf; 
uses SANE; 
var 

X: Extended; 
begin 

SetEnvironiBent(D); 
X := le^DDD; 
HriteLn('X*X - ',X*X); 
ffriteLn{'l/(X*X) = M/(X*X)); 
WriteLri('l+l/(X»X) = M+1/(X*X)); 
end. 

NaNs 

Another special SANE representation is NaN (Not-a- Number). A NaN is pro- 
duced whenever an operation cannot return a meaningful result. For example, 
0/0 and Sqrt(—1 ) produce NaNs. 

Each time a NaN is generated, an associated NaN code is returned as part of 
the NaN's representation. The code tells you what kind of operation caused the 
NaN. Table 26-2 shows these NaN codes, which you can use in debugging. 
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Table 26-2 NaN Codes 



Code 



Meaning 



1 

2 

4 

8 

9 

17 

20 

21 

33 

34 

36 

37 

38 

255 



Invalid square root, such as Sqirt{—1) 

Invalid addition, such as (+in/) — {+lnf) 

Invalid division, such as 0/0 

Invalid multiplication, such as 0 X Inf 

Invalid remainder, such as Remainder{Xfi,Q) 

Attempt to convert invalid ASCII string 

Result of converting the Comp NaN to floating-point format 

Attempt to create a NaN with a zero code 

Invalid argument to trig routine 

Invalid argument to inverse trig routine 

Invalid argument to log routine 

Invalid argument to x or routine 

Invalid argument to financial function 

Uninitialized storage (signaling NaN) 



The statement WriteLn(0/0) produces the result NAN(004) (assuming the 
invalid operation halt is ofl). NAN(004), nan(4), and NaN are all acceptable ways 
of reading a NaN into a SANE variable. 

Denormalized Numbers 

When possible, SANE stores values in normalized form; that is, the most signifi- 
cant bit of the significand is a one rather than a zero. 

How^ever, when a very small number is being stored, and the exponent is the 
smallest possible value, you can store still smaller values by storing leading 
zeroes. For example, 1.0.. 0^ x 2"^^^ is the smallest normalized Real, and d.-O^ 
X 2~^^ is a still smaller denormalized Real. 

The Environment 



The SANE environment consists of various settings that are global to all routines 
in the SANE library: 

• Rounding direction 

• Rounding precision 

• Exception flags 

• Halt settings 
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The SANE library includes procedures and functions that let you determine 
the current status of the environment, as well as change any of its settings. 

When your program begins, the environment is set to these Turbo Pascal 
defaults: 

• Rounding direction: To nearest 

• Rounding precision: Extended 

• All exception flags cleared 

• Halts on invalid operation, underflow, and divide-by-zero 

The entire SANE environment can be encoded in a value of the SANE type 
Environment. The GetEnmronment, SetEnviwnment, ProcEntry, and PwcExit pro- 
cedures access the current SANE environment as a whole. 

Rounding Direction 

The rounding direction can be set in four ways: 

• To nearest 

• Upward 

• Dovmward 

• Toward zero 

The default rounding direction is to nearest. You can find the current rounding 
direction using the GetRound function and change it using the SetRound func- 
tion. 

The following code shows how to save the current rounding direction, com- 
pute a function using toward zero rounding, and then restore the saved rounding 
direction. 

var 

R: RoandDir; 

X,Y: Extended; 
begin 

R := GetRound; 

SetRound(TowardZero) ; 

Y F(X); 

SetRound (R) ; 
end 
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Rounding Precision 

The rounding precision can be set in three ways: 

• Extended precision 

• Double precision 

• Real precision 

The default rounding precision is extended. You can use SANE to perform 
calculations and then simulate the results you would get using a system without 
extended precision arithmetic. The rounding precision is accessed through the 
SetPrecision procedure and the GetPrecision function. 

Exception Flags 

Exceptions can arise from floating-point calculations in a number of ways. For 
example, multiplying two very large values can result in a value too large to be 
represented in one of the SANE data types. 

SANE lets your program determine when a floating-point calculation has 
resulted in one of these exceptions. Exceptions faU into five categories: 

• Invalid operation 

• Underflow 

• Overflow 

• Divide-by-zero 

• Inexact 

Whenever one of these exceptions occurs, a corresponding flag is set in the 
environment. The flag remains set until explicitly cleared. The exception flags 
are accessed through the SetException procedure and the TestException fimc- 
tion. Below follows a description of each of the individual exceptions. 

Invalid Operation: The invalid operation exception occurs when the operands of 
an operation are invalid, so that a meaningful numeric result is impossible, for 
example, 0/0 and Sqrt(—1). 

Underflow: Underflow occurs when a result is both denormahzed and has lost 
significant digits through rounding. For example, to return the result of 

(l.DDDDDaDDDODDQDDDDDDDDDlg » I E 

to the real format, a leading zero would be introduced and last significant bit 
would be lost in rounding. The result 

D.lDDODDDDDDDQDDDDOODDDDDDQg » 2'^^'' 
would be returned, signaling an underflow. 
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Overflow: Calculating a value that is too large to fit in the format of its desig- 
nated type is an overflow. The destination format must be a floating-point type; if 
the destination format is an integral type, the invalid exception occurs. 

Divide-by-zero: This exception occurs when a finite non-zero number is divided 
by zero. It also occurs when an operation on finite operands produces an exact 
infinite result. For example, I/O (which results in Inf) and Ln(0) (which results in 
-Inj) both signal divide-by-zero. 

Inexact: The inexact exception occurs if the rounded result of an operation is not 
identical to its mathematical (exact) result. Whenever an overflow or underflow 
occurs, inexact is also signaled. For instance, 2/3 signals inexact, regardless of the 
floating-point format used. 

Halt Settings 

The SANE environment includes a halt setting for each exception that deter- 
mines whether occurrence of the exception halts the program. By default. Turbo 
Pascal sets a halt on invalid operation, overflow, and divide-by-zero. The IEEE 
standard default calls for all halts off. 

You can access the halt settings using the TestHalt function and the SetHalt 
procedure. 

The SANE Library 



The SANE library is implemented as a unit in Turbo Pascal. To use the features 
provided by SANE, you must specify SANE in the uses-clause of your program 
or unit: 

uses SANE; 

The rest of this chapter explains each of the constants, types, functions, and 
procedures contained in the SANE library. Some advanced and rarely used fea- 
tures have been left out; refer to the Apple Numerics Manual for a discussion of 
these. 

Constants and Types 



Each of the constants and types defined by SANE are briefly discussed in this 
section. For more information, see the descriptions of the procedures and func- 
tions that depend on these constants and types. 
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The DecStrLen Constant 

The DecStrLen constant is defined by: 
DecStrLen = 555; 

DecStrLen is the maximum length of a decimal numeric string. It is the size 
attribute of variables of type DecStr, 

Exception Condition Constants 

These declarations specify the exception condition constants: 



Invalid 


= 1; 


Underflow 


= a; 


Overflow 


= ^; 


DivByZero 


" fi; 


Inexact 


= It; 



These constants are used to form a value of the Exception type. For example, if 
E is a variable of type Exception, then: 

E := Invalid + Overflow + DivByZero; 

gives E a value that represents these three exceptions collectively. 

The SetException and SetHalt procedures take arguments of type Exception. 
The TestException and TestHalt fiinctions return a value of type Exception. 

The DecStr Type 

This declaration defines the DecStr (decimal string) type: 
DecStr = stringCDecStrLen] ; 

It is a string with a size attribute of DecStrLen (255 characters). It is used to 
hold the decimal representation, in ASCII characters, of a number. 

The DecForm Type 

The following declaration defines the decimal format record type: 

DecForm = record 

Style: (FloatDecimalr FixedDecimal) ; 
Digits: Integer; 
end; 

A DecForm record holds the specifications for the format of a decimal number. 
Its Style field specifies whether the decimal representation will be floating-point 
or fixed-point. Its Digits field holds the number of significant digits for float style 
or the number of digits to the right of the decimal point for fixed style. 

The Num2Str procedure takes a DecForm argument. 
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The RelOp Type 

The relational operator type is defined by 
RelOp = (GreaterThan, LessThan, EqualTO/ Unordered); 
A result of this type is returned by the Relation function. 

The NumClass Type 

The number class type is defined by 

NumClass = (SNaN, QNaN, Infinite, ZeroNum, NorinalNuni, DenorinalNuin) ; 
whose members are described in Table 26-3. 

Table 26-3 Number Class Descriptions 
Number Class Meaning 
SNaN Signaling NaN 

QNaN Quiet NaN 

Infinite Infinity or —Infinity 

ZeroNum 0 or —0 

NormalNum Normalized number 

DenormalNum Denormalized 
number 



A Quiet NaN moves through floating-point operations without signaling an 

exception (or halting a program). Signaling NaNs are not used in SANE opera- 
tions. They signal an Invalid exception when the NaN is an operand of an arith- 
metic operation. 

The inquiry functions return results of type NumClass. 
The Exception Type 

A variable of type Exception has an integer value corresponding to the value of an 
Exception constant or to a sum of two or more of the Exception constants. The 
Exception type is defined by 

Exception » Integer; 

The SetException, TestException, SetHalt, and TestHalt routines all take argu- 
ments of this type. 



312 



Turbo Pascal for the Macintosh 



The RoundDir Type 



The rounding direction type is defined by 

RoundDir = (ToNearest, Upward, Downward, TowardZero); 

The RoundDir type determines how values are to be rounded when rounding 
becomes necessary during arithmetic operations or conversions. The SetRound 
procedure takes an argument of type RoundDir, while the GetRound function 
returns a value of type RoundDir. 

The RoundPre Type 

The rounding precision type is defined by 

RoundPre » (ExtPrecision, DblPrecision, RealPrecision) ; 

Rounding precision can be used to simulate arithmetic using only single or 
double precision. The SetPrecision procedure takes an argument of type 
RoundPre, while the GetPrecision function returns a value of type RoundPre. 

The Environment Type 

A variable of type Environment represents the settings of the SANE environ- 
ment. A value of 0, for example, represents the default IEEE settings. The 
Environment type is defined by 

Environment = Integer; 

Use a variable of type Environment with the environmental access routines 
SetEnvironment, GetEnvironment, ProcEntry, and ProcExit. 

Conversion Procedures and Functions 



The SANE library contains procedures and functions that convert numeric 
values from one binary format to another, from binary to decimal, and from 
decimal to binary. These conversion procedures and functions are described in 
the following sections. 

The Nuw2Integer and Nuni2Longint Functions 

function NuinEInteger(x: Extended): Integer; 
function NuraELongInt(x: Extended): Longint; 
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The Num2Integer function takes an Extended argument and returns a result of 
type Integer, The Num2LongInt function takes an Extended argument and 
returns a result of type Longlnt. 

The value returned by these functions depend on the rounding direction (set 
with the RoundDir procedure). If you were to use the standard rounding direc- 
tion ToNearest, for example, 

NuinEInteger(SS.t) ; 
NumaLonglntiss.t) ; 

return the value 100. 

Nuin2Integer and Num2Longint are like Turbo Pascal's Round and Trunc func- 
tions. However, Num2Integer and Num2Longint are aflFected by the current 
rounding direction, whereas the Round function always returns the nearest 
Longint value, and the Trunc function always rounds toward zero. 

Using the ToNearest rounding direction, Num2Integer and Num2Longint 
round values that are halfway between two integers to the nearest even integer 
as indicated by the IEEE standard. For example, Num2Integer(2.5) returns 2. 
The Round function rounds these halfway values away from zero — Round(2.5) 
returns 3. 

The Num2Extended Function 

function NuinEExtended(x: Extended): Extended; 

Any real-type or integer-type argument can be passed to the Num2Extended 
function. It converts its argument to the Extended format, which forces floating- 
point arithmetic when all variables involved are of integer-types. 

The Num2Str Procedure 

procedure NuniEStr(f: DecForm; x: Extended; var s: DecStr); 

Converts an extended value x to a decimal string, returned in s, using the 
specifications in the DecForm record/ The Style field off determines the for- 
matting style. If /.Style is FhatDecimal, the number is formatted in floating- 
point style, and /.Digits determines the number of significant digits: 

[ I - ] <digit> [ . <deciinals> ] e [ + ! - 3 <exponent> 
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These are the components of the output string: 

[ ! - ] * or " according to the sign of x. 

< digit > Single digit, ^'OT only if x is 0. 

[ . <cleciinals> ] Digit string, present if /.Digits ) 1. 

e Lowercase ''e* character. 

[ + !~] "+''or"— according to sign of exponent. 

<exponent> One to four exponent digits . 

If /.Style is FixedDecimal, the number is formatted in fixed-point style, and 
/Digits determines the number of digits to follow the decimal point: 

[ - ] <cligits> [ . <decimals> ] 
These are the components of the output string: 

[ - 3 * if X is negative. 

<digits> At least one digit, but no leading zeros. 

[ . <deciraals> ] Decimals if/Digits ) 0. 

If /Style is FixedDecimal and x is greater than or equal to 10 ^ (19 — /Digits), 
the formatter will select floating-point style with 19 significant digits. In general, 
if /.Digits is outside the range 0..72, it is truncated to be within that range. 

NaNs (Not a Number values) are formatted as NAN(ddd) where ddd is a 
three-decimal-digit code telling the origin of the NaN. Infinities are formatted as 
INF. A sign or space is prepended according to the selected style. 



The Str2Num Function 

function Str5Num(s: DecStr): Extended; 

Converts a decimal string argument of type DecStr to a value of type 
Extended. The string may contain leading blanks or TABs, but no trailing charac- 
ters are allowed. Examples of acceptable input are 

1E3 lEB.-^E-lE -153. .45b 3eR -0 
-INF Inf NAN(15) ~NaN() nan 

The accepted syntax is presented below uising Backus-Naur form: 



<deciiaal number> 
<left deciinal> 
<unsigned deciinal> 
<finite nuniber> 
<significand> 
<integer> 



= [{space I tab}] (left decimal) 

_ [+|— ] {unsigned decimal) 

= {finite number) | (infinity) | (NAN) 

= (significand) [(exponent)] 

= (integer) | (mixed) 

= (digits) [.] 
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<NAN> 



<digits> 
<iiiixed> 
<exponent> 
<infinity> 



;:= {0|1|2|3|4|5|6|7|8|9} 
:= [{digits)] . (digits) 
:=E[+h] (digits) 
::= [+|-]INF 

NAN [( [(digits)] ) ] 



Note: In the table, square brackets enclose optional items, braces (curly 
brackets) enclose elements to be repeated at least once, and vertical bars sepa- 
rate alternative elements. Letters that appear literally, like the E marking the 
exponent field, may be either uppercase or lowercase. 

If the string is syntactically incorrect, Str2Num returns NAN(017), which is 
the code for invalid Decimal to Binary conversion. If the resulting value is out- 
side the floating-point range, Str2Num returns INF or —INF according to the 
sign of the value. 

Arithmetic and Auxiliary Functions 



The SANE library includes a set of functions that supplement the standard func- 
tions described in Chapter 25. 

The Remainder Function 

function Remainder (x,y: Extended; var quo: Integer); 

Returns an exact remainder of the smallest possible magnitude resulting from 
the division of its two Extended arguments x and t/, as prescribed by the IEEE 
standard. The result is computed as 



where n is the nearest integral approximation to the quotient x/y. For example, 
Remainder(9,5,q) returns —1, since —1 = 9—2x5. The integer variable argu- 
ment quo receives the seven low-order bits of n as a value between — 127 and 127. 
This is handy when programming a function that requires argument reduction. 

The Pascal operator mod can be used only with integral values. The 
Remainder function deals with real-type or integer-type values. 



x-n*y 
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The Rint Function 

function Rint(x: Extended): Extended; 

Rounds X to an integral value. All sufficiently large floating-point values are 
integral. Use the SetRound procedure to change the rounding direction for the 
result you want. Rint is the same as the standard function Int, except that Int 
always rounds toward zero. 

The Scalh Function 

function Scalb(n: Integer; x: Extended): Extended; 

Scales X by the power to two specified by n. The value 2" X x is returned in 
Extended format. 

The Logh Function 

function Logb(x: Extended): Extended; 

Returns the largest power of two that does not exceed the magnitude of x. 

The Copy Sign Function 
function CopySign(X/y rextended) :extended; 
Returns the value of y with the sign of x. 

The NextReal Function 
function NextReal (x,y: Real): Extended; 
Returns the next Real format value after x in the direction of t/. 

The NextDouble Function 
function NextDouble(x,y: Double): Extended; 
Returns the next Double format value after x in the direction of y. 

The NextExtended Function 

function NextExtended(x,y: Extended): Extended; 

Returns the next Extended format value after x in the direction of y. 
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Elementary and Trigonometric Functions 



Tiirbo Pascal provides the predefined Ln, Exp, Sin, Cos, and ArcTan functions. 
The SANE hbrary complements these with the Log2, Lnl, Exp2, Expl, Xpwrl, 
XpwrY, and Tan functions. 

The Log2 Function 
fanction Lo9d(x: Extended): Extended; 
Returns the base-2 logarithm of x. 

The Lnl Function 

function Lnl(x: Extended): Extended; 

Returns the base-^ logarithm of 1 plus x, that is, Lnl(x) = Ln(l+x), For x near 
0, Lnl(x) is more accurate than Ln(l-\-x), 

The Exp2 Function 
function Exp2(x: Extended): Extended; 
Returns 2 raised to the power of x, that is, 2^. 

The Expl Function 

function Expl(x: Extended): Extended; 

Returns e raised to the power of x, minus one, that is, e'—l. For x near 0, 
Expl(x) is more accurate than Exp(x)—L 

The Xpwrl Function 

function Xpwrl(x: Extended; i: Integer): Extended; 
Returns x raised to the power of i, that is, x\ 

The XpwrY Function 
function XpwrY(x,y: Extended): Extended; 
Returns x raised to the power of y, that is, x^. 
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The Tan Function 



function Tan(x: Extended): Extended; 

Returns the tangent of x. In a right triangle, Tan(x) is the ratio of the length of 
the side opposite an angle of x radians to the length of the side adjacent to it. x 
must be expressed in radians. 



Financial Functions 



SANE offers two functions for financial applications: Compound and Annuity, 



The Compound Function 

function Coinpound(r/n: Extended): Extended; 

Returns the compound interest, r specifies the interest rate and n specifies the 
number of periods. The value returned is (i-l-r/, which is the principal plus 
accrued compound interest on an original one-unit investment. 



The Annuity Function 

function Annuity (r,n: Extended): Extended 

r specifies the interest rate and n specifies the number of periods. Annuity 
returns (l-'(l'^-r)'yr, the present value factor of an ordinary annuity. It returns 
an Extended value. Following is an example of use of the Annuity function: 

prograa PayBack; 
var 

Loan, Payient, Interest /Periods: Extended; 
begin 

Write('Loan amount: '); 
ReadLn(Loan) ; 

Write( 'Annual interest rate (enter as a decminal): '); 

ReadLn(Interest) ; 

Write( 'Nuiber of years: '); 

ReadLn(Periods) ; 

Payment := Loan / Annuity (Interest / IE, Periods * IE); 
WriteLn( 'Your payment is: ' ,Payiiient:fl:E) ; 
end. 
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Inquiry Functions 



SANE oflFers four functions that let you determine the class of a numeric value, 
and one that returns the sign of a numeric value. The result of the four classifica- 
tion functions is of type NumClass. 

The ClassReal Function 

function ClassReal(x: Real): NumClass; 

Returns the number class of the Real type value x. For example, ClassReal(l ) 
returns NormalNum, which is the code for a normalized number. ClassReal 
(le-310) returns ZeroNum, the code for zero, because le— 310 rounds to +0 in 
the Real format. 

The ClassDouhle Function 

function ClassDouble(x: Double): NumClass; 

Returns the number class of the Double type value x. For example, Class- 
Double(0.0/0.0) returns QNan, and ClassDouble(le-310) returns Denormal- 
Num, because le^lO is denormalized in the Double format. 

The ClassExtended Function 

function ClassExtencled(x: Extended): NumClass; 

Returns the number class of the Extended type value x. For example. Class- 
Extended(l/0) returns Infinite, and ClassExtended(le'-310) returns NormalNum, 

The ClassComp Function 

function ClassComp(x: Corap): NuiClass; 

Returns the number class of the Comp type value x. For example, Class- 
Comp(l) returns NormalNum, while ClassComp(O.l) returns ZeroNum, as 
Comp stores only integral values. 

The SignNum Function 

function SignNum(x: Extended): Integer; 

Returns an integer value that reflects the sign of x: 1 is returned if x is nega- 
tive, and 0 is returned if x is positive. 
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Miscellaneous Functions 



This section describes the RandomX, NaN, and Relation functions. 

The RandomX Function 

fanction RancloiRX(var x: Extended): Extended; 

RandomX takes a variable argument of type Extended that contains an integral 
value in the range l{r{ 2^^— 2. It returns the next random number (in Extended 
format) in sequence within the same range. The variable argument is updated to 
the value returned. RandomX uses the algorithm: 

NewX -(7^ * OldX) lod (a^"*-!) 

The NaN Function 

function NaN(x: Integer): Extended; 

Returns a NaN with the code specified by x. See Table 26-2 for a hst of defined 
NaN codes. 

The Relation Function 

function Relation (X/y: Extended): BelOp; 

Returns a value of type RelOp that specifies the relationship between x and 
For example, 

Relation(D.l,NaN(D)); 

returns Unordered, since all comparisons involving NaNs are unordered. 
Environmental Access Procedures and Functions 



The SANE library provides a number of procedures and functions to access the 
SANE environment. They are described in this section. 

The GetRound Function 
function GetRound: RoundDir; 

Returns the current rounding direction. 
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The SetRound Procedure 
procedare SetB6und(r: RoundDir); 
Sets the rounding direction to the value specified by r. 

The GetPrecision Function 
f auction GetPrecision: RoundPre; 
Returns the current rounding precision. 

The SetPrecision Procedure 
procedure SetPrecision(p: RoundPre) ; 

Sets the rounding precision to the value specified by p. 

The TextException Function 

function TestException(e: Exception): Boolean; 

Returns true if any of the exceptions encoded in e are set. For example, 
Error := TestException{Overf low + Inexact); 

would set Error to true if the overflow and/or inexact exception flags were set. 

The SetException Procedure 

procedure SetException(e: Exception; b: Boolean); 

The exceptions encoded in e are set or cleared according to the value of fo: If b 
is true, the flags are set; if is false, the flags are cleared. For example, 

SetException (Overflow + Inexact, true); 

This statement signals the overflow and inexact exceptions. If halt on overflow 
or inexact were set, this statement would halt the program. 

The TestHalt Function 

function TestHalt(e: Exception): Boolean; 

Returns true if any of the halt flags encoded in e are set, that is, if halts are 
enabled for any of the specified exceptions. 
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The SetHalt Procedure 



procedure SetHalt(e: Exception; b: Boolean); 

The halt flags encoded in e are set or cleared according to the value of b: If b is 
true the flags are set, and if b is false the flags are cleared. When a specific flag is 
set and the corresponding exception occurs, the program comes to a halt. 

The GetEnvironment Procedure 
procedure 6etEnvironinent(var e: Environment); 
Stores the current settings of the environment in e. 

The SetEnvironment Procedure 
procedure SetEnvironDient(e: Environment); 

Sets the environment to the value encoded in e. To install the IEEE standard 
defaults, use the statement 

SetEnvironment(D) ; 

The following procedure runs with the IEEE default environment, while pre- 
serving the callers environment: 

procedure P; 
var 

E: Environment; 
begin 

GetEnvironnient(E) ; 
SetEnvironment(D) ; 



SetEnvironment (E) ; 
end; 

The ProcEntry Procedure 

procedure ProcEntry (var e: Environment); 

Stores the current settings of the environment in e, and then sets the environ- 
ment to the IEEE defaults. The statement 

ProcEntry (E ) ; 
is equivalent to 

GetEnvironment(E); 
SetEnvironment(D) ; 
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The ProcExit Procedure 



procedure ProcExit(e: Environment) ; 

ProcExtf temporarily saves the current exception flags, then sets the environ- 
ment to the value encoded in e, and finally signals the temporarily saved excep- 
tions. 

ProcEntry md ProcExit csm be used in routines to hide specific spurious 
exceptions from the caller, for example, 

function ArcCos(x: Extended): Extended; 
var 

E: Environment; 
begin 

ProcEntry(E) ; 

flrcCos := ArcTan(Sqrt(1.0-x)/(l.D+x))); 
SetException(DivByZero/false) ; 
ProcExit (E); 
end; 

ProcEntry(E) saves the caller s environment in E and sets IEEE defaults, so 
exceptions cannot halt the routine. If oc = 1, the computation of ArcCos signals 
divide-by-zero, even though ArcCos is assigned the correct value (Pi/2). The call 
to SetException clears the divide-by-zero flag, so the caller never sees it. If x > 1 
or X < —1, the computation of ArcCos signals invalid operation. The ProcExit 
procedure will resignal invalid operation after it restores the caller s environ- 
ment, and if the caller s environment calls for halts on invalid operation, the halt 
occurs. 
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CHAPTER 



Inside Turbo Pascal 



This chapter provides additional information for advanced Pascal programmers. 
It covers Macintosh architecture, internal data formats, interfacing with assem- 
bly language, and defining your own device drivers. 



Macintosh Architecture 



The environment in which a Macintosh application runs may be divided into five 
basic components: the Jump Table, the Application Parameters, the Application 
Ghbals, the Stack, and the Application Heap, The organization is shown on the 
following page. 



325 



Jump Table 



A5-> 



Application Parameters 



Application Globals 



Stack 



SP-> 



1 1 1 1 1 1 1 1 1 u I N 1 1 1 u 11 1 1 1 1 1 n / 1 
1 1 1 11 1 1 1 1 1 1 u u 1 1 1 n 1 1 1 1 1 1 1 1 1 1 
I u 1 1 1 1 1 11 1 1 1 1 1 1 n 1 1 // n 1 1 / 1 1 1 



Application Heap 



Top of Memory 



Bottom of Stack 

Top of Stack 

Heap Limit 
End of Heap 

Heap Origin 



When an application starts up, the processor's A5 register is set to point to the 
boundary between the Apphcation Parameters and the AppUcation Globals. The 
Application Parameters and the Jump Table thus reside at positive offsets from 
A5 (above A5) and the Application Globals reside at negative offsets from A5 
(below A5). 

The Application Parameters area occupies the first 32 bytes above A5. It con- 
tains the QuickDraw Globals Pointer at 0(A5) and the FINDER Startup Handle 
at 16(A5). 

The remainder of the area above A5 is occupied by the Jump Table, which is 
maintained by the Segment Loader, For each segment, it contains one eight-byte 
entry for every procedure or function that is referenced from another segment. 
When a segment is in the ^'unloaded" state, its Jump Table entries contain code 
that cause the segment to be loaded. When a segment is in the '^loaded'' state, its 
Jump Table entries contain instructions that jump to the routines. 

The area below A5 contains the application's global variables and the Quick- 
Draw global variables. 

The Stack follows below the Application Globals, When an application starts 
up, the processor's stack pointer register (referred to as A7 or SP) is set to point 
just below the Application Globals. 

Stack space is always allocated and released in LIFO (last-in/first-out) order: 
The last item allocated is always the first to be released. The SP register always 
points to the ^^top** of the stack — note that the stack grows downwards, and that 
the ''top* of the stack is actually the lower end of the stack in memory. 



326 



Turbo Pascal for the Macintosh 



The LIFO nature of the stack makes it convenient for memory allocation con- 
nected with the activation and deactivation of procedures and functions. Each 
time a routine is called, space is allocated for a stack frame. The stack frame 
holds the routine's parameters, local variables, and return address. Upon exit- 
ing, the stack frame is released, restoring the stack to the same state it was in 
when the routine was called. The processor's A6 register functions as a stack 
frame pointer. 

The Application Heap is an area in memory from which storage can be allo- 
cated or deallocated in any order. The heap is maintained by the Memory 
Manager. All dynamic storage required by a program is allocated on the heap. 
This includes dynamic variables {New and Dispose), code segments, resources, 
windows, menus, and dialogs. 

Two types of blocks can be allocated on the heap: Non-relocatable blocks and 
relocatable blocks. 

Non~relocatable blocks reside at a fixed locations in the heap, and cannot be 
moved once they have been allocated. A non-relocatable block is referenced 
through a pointer. 

Relocatable blocks may be moved by the Memory Manager to make room for 
new allocation requests. As a relocatable block may move, it cannot be refer- 
enced through a pointer. Instead, the Memory Manager maintains a single non- 
relocatable master pointer to each relocatable block: When the block moves, the 
master pointer is updated to reflect the new position of the block. You access 
the block through a handle, which is a pointer to the master pointer. To get 
at a block through a handle, the handle is de-referenced twice, for instance 
MYHANDLE^^. 

More information on memory management can be found in the Memory Man- 
ager chapter of Inside Macintosh. 

Internal Data Formats 



The compiler always aligns variables to even addresses (word boundaries) unless 
they occupy a single byte. 

Integer-Types 



An Integer is stored as a 16-bit two's-complement number with a range of 
-32768 to 32767. 
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A Longint is stored as a 32-bit two's-complement number with a range of 
-2147483648 to 2147483647. 

A subrange of an integer-type is stored as a signed quantity. If the range is 
within - 128 to 127, a byte is used; if the range is within -32768 to 32767, a word 
is used; otherwise, a longword is used. 

Note: The integer- type subrange 0..255 is stored as an unsigned byte if it is 
part of a packed structure. 

Char-Types 



A Char is stored as a word with the ASCII code in the low-order byte, and 0 in 
the high-order byte. 

A subrange of a char-type is stored as a byte if the range is within #0 to #127; 
otherwise, it is stored as a word. 

Note: A Char is stored as an unsigned byte if it is part of a packed structure. 
Boolean-Type 



A Boolean is stored as a byte that may assume the values 0 {False) or 1 (True). 
Enumerated-Types 



An enumerated-type is stored as a byte if the enumeration has 128 or fewer 
values; otherwise, it is stored as a word. 

Real-Types 



A Real or a Single is stored in 4 bytes using the IEEE Single-Precision format. A 
Double is stored in 8 bytes using the IEEE Double-Precision format. An 
Extended is stored 10 bytes using the IEEE Extended-Precision format. A Comp 
is stored as a 64-bit two's-complement number. 

For further details on floating-point formats, please refer to Chapter 26. 
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Pointer-Types 



A pointer-type is stored as a 32-bit address value. The pointer value nil is stored 
as zero. 

String-Types 



A string occupies as many bytes as its maximum length plus one. The first byte 
contains the current dynamic length of the string, and the following bytes con- 
tain the characters of the string. The length byte and the characters are consid- 
ered unsigned values. 

Set-Types 



A set is a bit-array where each bit indicates whether an element is in the set or 
not. The maximum number of elements in a set is 256, so a set never occupies 
more than 32 bytes. The number of bytes occupied by a particular set is calcu- 
lated as 

(Max div fl) - (Min div fl) + 1 

where Min and Max are the lower and upper bounds of the base-type of that set. 
The byte number of a specific element E is 

ByteNumber = (E div fi) - (Min div fl) 

and the bit number within that byte is 

BitNumber = E mod fl 

where E denotes the ordinal value of the element. 
Array-Types 



An array is stored as a contiguous sequence of variables of the component-type 
of the array. If the size of the component-type is greater than one, it is rounded 
up to an even value so that each component resides on an even boundary. The 
components with the lowest indices are stored at the lowest memory addresses. 
A multi-dimensional array is stored with the right-most dimension increasing 
first. 
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A packed array is identical to the corresponding unpacked array, unless the 
component-type is Char or the integer subrange 0. .255. In that case the compo- 
nents are stored as single-byte unsigned quantities. 



Record-Types 



The fields of a record are stored as a contiguous sequence of variables. If the size 
of a specific field is greater than one, it is aligned to an even boundary. The first 
field is stored at the lowest memory address. If the record contains variant parts, 
then each variant starts at the same address. 

A packed record is identical to the corresponding unpacked record, unless any 
of the fields are of type Char or the integer subrange 0..255. In that case, these 
fields are stored as single-byte unsigned quantities. 

File-Types 



File-types (typed-files and textfiles) are represented as records that contain 20 
bytes of file status information: 



flnpFlag: Boolean; 
fOutFlag: Boolean; 
fRefNum: Integer; 
fVRefNum: Integer; 
fBufSize: Integer; 
fBufPos: Integer; 
fBufEnd: Integer; 
f Buffer: BufferPtr; 
fInOutProc: ProcPtr; 
end; 



flnpFlag is true if the file was opened with Reset. fOutFlag is true if the file 
was opened with Rewrite. Both are false if the file is closed. fRefNum SLud fVRef- 
Num contain the file reference number and the volume reference number. 

For typed files, fBufSize contains the record length in bytes, and fBufPos, 
fBufEnd, fBuffer, and flnOutProc are unused. 

When a textfile is opened, Turbo Pascal allocates an I/O bufier by calling the 
Memory Manager's NewPtr routine and stores a pointer to it in fBuffer. The 



type 



Buffer 

BufferPtr 

ProcPtr 



packed arrayCD. .Maxlntl of Char; 

'^Buffer; 

'^Integer; 



FileRec 



record 



330 



Turbo Pascal for the Macintosh 



buflFer is deallocated by a call to the Memory Manager's DisposPtr routine when 
the file is closed. fBufSize contains the size of the buflFer (default 512), fBufPos 
contains the index of the next character to read or write, and fBufEnd contains a 
count of valid characters in the buffer. 

If a textfile is associated with a device, fRefNum s^nd JVRejNum are zero, and 
flnOutProc contains a pointer to the I/O routine that handles I/O for that device. 
The section **Defining Your Own Devices" in the following pages provides that 
information. 



Calling Conventions 



Turbo Pascal uses the standard stack-based parameter passing conventions as 
defined in Inside Macintosh. 

Before calling a procedure or function, the parameters are pushed onto the 
stack in their order of declaration. If a function is being called, storage for the 
function result is allocated on the stack before any parameters are pushed. 
Before returning, the procedure or function removes all parameters from the 
stack, but leaves the function result (if any) on the stack. 

The skeleton code for a procedure call is 
MOVE PPPP^-(SP) ;Push first parameter 

MOVE PPPP/-(SP) ;Push last parameter 

JSR Procedure ;Call procedure 

The skeleton code for a function call is 

SUBQ.L #nn,-(SP) ;Make room for result 

MOVE PPPP/-(SP) ;Push first parameter 

MOVE PPPP/-(SP) ;Push last parameter 

JSR Function ;Call function 

MOVE (SP)+,rrrr ;Get result 

Parameters are passed either by reference or by value. When a parameter is 
passed by reference, a pointer that points to the actual storage location is pushed 
onto the stack. When a parameter is passed by value, the actual value is pushed 
onto the stack. 



Variable Parameters 



Variable parameters (var parameters) are always passed by reference, that is, as a 
pointer that points to the actual storage location. 
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Value Parameters 



Value parameters are passed by value or by reference depending on the type and 
size of the parameter. In general, if the value parameter occupies 4 bytes or less, 
the value is pushed directly onto the stack. Otherwise a pointer to the value is 
pushed, and the procedure or function then copies the value into a local storage 
location. 

NOTE: To keep the stack properly aligned, the 68000 automatically adjusts 
the stack pointer by 2 instead of 1 when moving a byte-size value to or from the 
stack. Thus, a byte-size value occupies a word on the stack, where the high-order 
byte contains the value and the low-order byte is unused. 

An Integer is passed as a word. A Longint is passed as a long. An integer-type 
subrange is passed: as a byte if the range is within —128 to 127; as a word if the 
range is within -32768 to 32767; otherwise, as a long. 

A Char is passed as a word with the ASCII code in the low-order byte and 0 in 
the high-order byte. A char-type subrange is passed as a byte if the range is 
within #0 to #127, otherwise as a word. 

A Boolean is passed as a byte with the value 0 or 1. 

An enumerated-type is passed as a byte if the enumeration has 128 or fewer 
values; otherwise, it's passed as a word. 

A real-type parameter (Real, Single, Double, Extended, and Comp) is passed 
as a pointer to an Extended value, 

A string- type parameter is passed as a pointer to the value. 

A set-type parameter is passed as a pointer to an ^^unpacked" set, which 
occupies 32 bytes. 

Arrays and records whose sizes are less than or equal to 4 bytes are passed by 
pushing their value onto the stack. Larger arrays and records are passed as a 
pointer to the value. 

Function Results 



For function results of type Integer, Longint, Char, and Boolean, and for func- 
tion results of any subrange or enumerated type, the caller allocates 2 or 4 bytes 
on the stack before pushing any parameters. The function places the result in 
these bytes using the same formats as value parameters; that is, the value is 
returned as a byte, a word, or a long. 
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For a real-type function result, the caller pushes a pointer to a temporary 
storage location before pushing any parameters, and the function returns an 
Extended value in that temporary. The caller removes the pointer from the stack 
when the function returns. 

For a string-type function result, the caller pushes a pointer to a temporary 
storage location before pushing any parameters, and the function returns a string 
value in that temporary. The caller removes the pointer from the stack when the 
function returns. 



Entry and Exit Code 



Each Pascal procedure and function begins and ends with standard entry and 
exit code which creates and removes its activation. 

The standard entry code is 

LINK At,#-dcl ;Set up stack frame 

MOVEM.L D3-D7/A2-A<,-(SP) ;Save registers 

where dd is the number of bytes of local workspace to allocate. The MOVEM 
instruction is only present if the procedure or function uses any non-scratch 
registers, and it only saves the registers that are actually used. 

The standard exit code is 

MOVEM.L (SP)+,D3-D7/RE-A^ ;Restore registers 
UNLK At ; Remove stack frame 

MOVE.L (SP)+,AD ;Get return address 

LEA pp(SP)/SP ; Remove parameters 

JMP (AD) ; Return 

where pp is the size of the parameters. (If pp is less than or equal to 8, an 
ADDQ.L instruction is used instead of a LEA instruction.) The MOVEM 
instruction (if present) lists the same registers as its counterpart in the entry 
code. 

If the procedure or function has no parameters the exit code is 

MOVEM.L (SP)+,D3-D7/AE-A4 ;Restore registers 
UNLK At ; Remove stack frame 

RTS ; Return 
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Unking with Assembly Language 



Procedures and functions written in assembly language may be linked with 
Turbo Pascal programs or units through {$L FileName} compiler directives. The 
assembly-language source file must be assembled into an object file using 
Apple's MDS assembler or an equivalent. 

Multiple object files may be linked with a program or unit through multiple 
directives. Note that all $L directives must appear before the begin that heads 
the main statement-part of the program or unit. If a $L directive appears in a 
program, the object file is linked into the blank segment, that is, the segment in 
which the main program resides. 

Procedures and Functions 



Procedures and functions written in assembly language must be declared as 
external in the Pascal program or unit, for instance: 

function UpCase(Ch: Char): Char; external; 

In the corresponding assembly-language source file, externally defined proce- 
dures and functions must appear in XDEF directives, for instance: 



XDEF 


DpCase 




jDefine UpCase 


UpCase 


MOVE.L 


(SP)+,AD 


;Get return address 


MOVE.W 


{SP)+,DD 


;Get Ch 




CMP.W 


#'a',DO 


;Skip if not lower case 




BLT.S 


@1 




CMP.W 


#'z',DD 






BGT.S 


@1 






SOB.W 


#$50, DD 


;Convert to upper case 




MOVE.W 


DD,(SP) 


; Store return value 




JMP 


(AD) 


; Return 



It is up to you to ensure that an assembly-language procedure or function 
matches its Pascal definition with respect to the number of parameters, the 
types of the parameters, and the result type. 

An assembly-language source file may reference Pascal procedures and func- 
tions via XREF directives, for instance: 

XREF ReadFile ;ReadFile is a Pascal routine 

JSR ReadFile ;Call ReadFile 

You must not specify the addressing base, such as (A5) or (PC), when calling an 
XDEFed or XREFed procedure or function. Turbo Pascal itself figures out 
which calling method to use when it links the object file with the program. 
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Variables 



An assembly-language source file may declare variables via DS directives. Such 
variables are private to the assembly-language source file and cannot be refer- 
enced from the Pascal program or unit. 

Global variables defined in the Pascal program or unit are referenced in 
assembly language via XREF directives, for instance: 

XREF ErrCnt ;ErrCnt is a Pascal variable 

aDDQ.W #lrErrCnt{A5) ;IiicreiBeiit ErrCnt 

The (A5) addressing base must be specified, just as it is for private variables 
defined via DS directives. 

Operations on Relocatable Symbols 



An assembly-language symbol is relocatable if it is created as a label or through 
an XREF directive. When a relocatable symbol appears in an assembly-language 
expression, the assembler cannot calculate the true value of the expression, since 
the value of the symbol is not determined until the object file is linked. For 
instance, if Symbol is defined via a DS directive, the address expression Sym- 
bol (AS) is not resolved until the object file is linked. 

When an object file appears in a $L compiler directive, Turbo Pascal converts 
the object file from MDS Link format to its own internal link format. This con- 
version is possible only if the following rules are observed in the Assembly Lan- 
guage source file: 

• XDEFed and XREFed procedure and function symbols may only be used as 
operands in JSR, JMP, PEA, and LEA instructions. For instance, if Proc is a 
procedure or function symbol, the instruction BRA Proc is not allowed. Fur- 
thermore, procedure and function symbols may not participate in assembly- 
language expressions. For instance, the instruction JSR Proc+4 is not allowed. 

• When a relocatable symbol is part of an assembly-language expression, the 
expression may only add an absolute value to the symbol or subtract an abso- 
lute value from the symbol. For instance, if Syml and Sym2 are relocatable 
symbols, the expressions Syinl+^ and Syni2-fl are allowed, whereas Synil»fl, 
fl-Syma, and Syni2-Syml are not. 

• Assembly-language expressions that involve relocatable symbols are evaluated 
as 16-bit integers and can only be coded as such. For instance, if Symbol is a 
relocatable symbol, the address expression Syinbol(A5,DD.W) is not allowed, 
since it would produce an 8-bit displacement. Likewise, the directive DC.L 
Syibol-* is not allowed, since it would produce a 32-bit value. 
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Register Saving Conventions 



An assembly-language procedure or function may modify registers D(X-D2, AO, 
and Al (the scratch registers). All other registers must be saved and restored. In 
particular, you should avoid modifying A5 and A7, and only modify A6 in connec- 
tion with LINK and UNLK instructions. 



Defining Your Own Devices 



In addition to the standard Console and Printer devices, Turbo Pascal allows you 
to define your own devices. 

The Device Procedure 



To define a device, you call the Device standard procedure, which supplies a 
device name and a pointer to a device I/O function. The device name identifies 
the device, and the device I/O function handles all input and output requests for 
the device. The Device procedure resides in the PasInOut unit, so if you are 
compiling in the {$U-} state, your program must name the PasInOut in its uses- 
clause. 

The syntax of a call to Device is 
Device ( name , inoutptr ) 

where name is a string- type expression that names the device, and inoutptr is 
an expression of any pointer-type that points to the device I/O function. An 
example is 

DeviceCMyDevice:', ©MylnOut); 

When a file is opened with Reset or Rewrite, Turbo Pascal scans the device 
name list, and associates the file with a device if a matching device name is 
found. Otherwise the file variable is associated with a disk file. 
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Device I/O Functions 



The function header of a device I/O function is 
function DevInOut(var F: FileRec): Integer; 

where FileRec is the file record type defined in the previous section, ^Tile- 
Types.'' 

NOTE: FileRec is not a predefined type; you must define it yourself. The 
names of the device I/O function and the parameter are unimportant, but the 
parameter must be a var parameter of a FileRec like type, and the function result 
must be Integer. 

The device I/O function is called by the Read, ReadLn, Write, WriteLn, 
Close, Eof, Eoln, SeekEof, and SeekEoln standard procedures and functions 
whenever input from the device or output to the device is required. 

The device I/O function determines whether it should read or write by looking 
at the flnpFlag sndfOutFlag fields of the file record (both flags are never set at 
the same time). 

liflnpFlag is set, the device I/O function should resd fBufSize or less charac- 
ters into the bufiFer pointed to by /Buffer, and it should return the number of 
characters actually read in JBufEnd and zero iffBufPos. If the device I/O func- 
tion returns zero in fBufEnd as a result of an input request, Eqf(f) becomes True 
for the file. 

If fOutFlag is set, the device I/O function should write fBufPos characters 
fi"om the buffer pointed to hy /Buffer, and return zero in/Bu/Pos. The device I/O 
function is called after each write-parameter in a Write or WriteLn statement. 
This ensures that text written to the device appears on the device immediately. 
If this is not required, the device I/O function may choose to ignore write 
requests if /Bu/Pos does not equal ^Bw/End. In that case, the buffer is not emp- 
tied until it is completely full. 

The return value of the device I/O function becomes the value returned by 
lOResult. Zero indicates a successful operation. 
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Examples of Device I/O Functions 



This section presents two simple device I/O functions that illustrate diflFerent 
ways of implementing device I/O in Turbo Pascal. 

The examples assume that three low-level procedures and functions exist: An 
InputChar(Ch) procedure that inputs a character from the device and stores it in 
Ch, an OutputChar(Ch) procedure that outputs the character in Ch to the 
device, and a CharReady function that returns true as long as there are still 
characters to be read fix)m the device. 

The device I/O functions implement two devices called 'BlockDev:' and 
*LineDev:'. They are defined by executing 

Device ( 'BlockDev: ^BlockliiOut) ; 
DeviceC'LineDev: '/ ©LinelnOut) ; 

The BhckDev function shown below uses the block-oriented method for doing 
I/O. When requested for input, it fills the entire buflFer; when requested for 
output, it only starts sending data out when the bufiFer is completely full. This 
method resembles the one used to input from and output to disk files. 

function BlockInOut(var F: FileRec): Integer; 
var 

Ch: Char; 
P: Integer; 
begin 

MylnOut := D; 

with F do 

if flnpFlag then 

begin 

fBufEnd := D; 

while CharReady and (fBufEnd < fBufSize) do 
begin 

InputChar(Ch) ; 

fBuffer'^t fBufEnd] := Ch; 

fBufEnd := fBufEnd + 1; 
end; 

fBufPos := D; 
end else 

if (fBufPos = fBufEnd) then 
begin 

for P := 0 to fBufPos - 1 do 
OutputChar ( f Buf f er** [ P 3 ) ; 
fBufPos := D; 
end; 
end; 
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The LinelnOut function shown below uses the line-oriented method for doing 
I/O. When requested for input, it inputs one line (which is ended by a GR 
character), and when requested for output, it outputs the contents of the buflFer 
immediately. This method resembles the one used by the Console device. 

function TextInOut(var F: FileRec): Integer; 
var 
Ch: Char; 
P: Integer; 
begin 
MylnOut := 0; 
with F do 
if flnpFlag then 
begin 

fBufEnd ;= D; 
if CharReady then 
repeat 

InputChar(Ch) ; 
fBuffer'*[ fBufEnd] := Ch; 
fBufEnd := fBufEnd + 1; 
until not CharReady or (fBufEnd = fBufSize) or (Ch = #13); 
fBufPos := D; 
end else 
begin 

for P D to fBufPos - 1 do 
Ou tputChar ( f Buf f er'* [ P ] ) ; 
fBufPos := D; 
end; 
end; 
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APPENDIX 



Comparing Turbo Pascal 
with Other Pascals 



This appendix compares Turbo Pascal with the American National Standard 
(ANS) Pascal and Lisa Pascal (Apple Computer's Pascal compiler for the Lisa 
computer). 

Turbo Pascal Compared to ANS Pascal 



This section compares Turbo Pascal to ANS Pascal as defined by ANSI/ 
IEEE770X3. 97-1983 in the book American National Standard Pascal Computer 
Programming Language (ISBN 0-471-88944-X, published by The Institute of 
Electrical and Electronics Engineers in New York). 

Exceptions to ANS Pascal Requirements 



Turbo Pascal complies with the requirements of ANSI/IEEE770X3. 97-1983 with 
the following exceptions: 

• In ANS Pascal, an identifier may be of any length and all characters are signifi- 
cant. In Turbo Pascal, an identifier may be of any length, but only the first 63 
characters are significant. 
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• In ANS Pascal, the @ symbol is an alternative for the ^ symbol. In Turbo 
Pascal, the @ symbol is an operator, which is never treated identically with 
the ^ symbol. 

• In ANS Pascal, a comment may begin with { and end with *), or begin with (* 
and end with }. In Turbo Pascal, comments must begin and end with the same 
set of symbols. 

• In ANS Pascal, each possible value of the tag-type in a variant-part must 
appear once. In Turbo Pascal, this requirement is not enforced. 

• In ANS Pascal, the component-type of a file-type may not be a structured-type 
having a component of a file-type. In Turbo Pascal, this requirement is not 

enforced. 

• In ANS Pascal, a file-variable has an associated bufier-variable, which is refer- 
enced by writing the ^ symbol after the file-variable. In Turbo Pascal, a file- 
variable does not have an associated buflFer-variable, and writing the ^ symbol 
after a file-variable is an error. 

• In ANS Pascal, the statement-part of a function must contain at least one 
assignment to the function identifier. In Turbo Pascal, this requirement is not 
enforced. 

• In ANS Pascal, a field that is the selector of a variant-part may not be an actual 
variable parameter. In Turbo Pascal, this requirement is not enforced. 

• In ANS Pascal, procedures and functions allow procedural and fimctional 
parameters; these parameters are not allowed in Turbo Pascal. 

• In ANS Pascal, the standard procedures Reset and Rewrite take only one 
parameter, a file variable. In Turbo Pascal, Reset and Rewrite require a second 
parameter, a string-type expression, which names an external file. 

• ANS Pascal defines the standard procedures Get and Put, which are used to 
read firom and write to files. These procedures are not defined in Turbo Pascal. 

• In ANS Pascal, the standard procedures Read and Write are defined in terms 
of Get and Put and references to buffer- variables. In Turbo Pascal, Read and 
Write fiinction as in ANS Pascal, but they are automatic operations. 

• In ANS Pascal, the syntax New(p,cl,..,,cn) creates a dynamic variable with a 
specific active variant. In Turbo Pascal, this syntax is not allowed. 

• In ANS Pascal, the syntax Dispose(q,kl,,..,km) removes a dynamic variable 
with a specific active variant. In Turbo Pascal, this syntax is not allowed. 

• ANS Pascal defines the standard procedures Pack and Unpack, which are used 
to '^pack" and "unpack** packed variables. These procedures are not defined in 
Turbo Pascal. 

• In ANS Pascal, the term i modj always computes a positive value, and it is an 
error ifj is zero or negative. In Turbo Pascal, i modj is computed as i - (t divj) 
* J, and it is not an error ifj is negative. 
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• In ANS Pascal, a goto statement within a block may refer to a label in an 
enclosing block. In Turbo Pascal, this is an error. 

• In ANS Pascal, it is an error if the value of the selector in a case statement is 
not equal to any of the case-constants. In Turbo Pascal, this is not an error; 
instead, the ease statement is ignored unless it contains an otherwise clause. 

• In ANS Pascal, statements that threaten the control-variable of a for statement 
are not allowed. In Turbo Pascal, this requirement is not enforced. 

• In ANS Pascal, a Read from a text file with a char- type variable assigns a blank 
to the variable if Eoln was True before the Read. In Turbo Pascal, a carriage- 
return character (ASCII 13) is assigned to the variable in this situation. 

• In ANS Pascal, a Read from a text file with an integer-type or real-type vari- 
able ceases as soon as the next character in the file is not part of a signed- 
integer or a signed-number. In Turbo Pascal, reading ceases when the next 
character in the file is a blank or a control character (including the end-of-line 
character). 

• In ANS Pascal, a Write to a text file with a packed-string-type value causes the 
string to be truncated if the specified field width is less than the length of the 
string. In Turbo Pascal, the string is always written in full, even if it is longer 
than the specified field width. 

Note: Turbo Pascal is unable to detect whether or not a program violates any of 
the exceptions listed here. 

Extensions to ANS Pascal 



The following Turbo Pascal features are extensions to Pascal as specified by 
ANSI/IEEE770X3.97-1983. 

• The following are reserved words in Turbo Pascal: 

implementation otherwise shr unit xor 

interface shl string uses 

• An identifier may contain underscore characters after the first character. 

• Integer constants may be written in hexadecimal notation. Such constants are 
prefixed by a 

• Identifiers may serve as labels. 

• String constants are compatible with the Turbo Pascal string-types, and may 
contain control characters and other non-printable characters. 

• Label, constant, type, variable, procedure, and function declarations may 
occur any number of times in any order in a block. 
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• A signed constant identifier may denote a value of type Integer, Longint, or 
Extended, 

• Turbo Pascal implements the additional integer-type Longlnt, and the addi- 
tional real-types Double, Comp, and Extended. 

• Arithmetic operations on Integer operands produce Integer results. Arithme- 
tic on LongInt operands or mixed Integer and LongInt operands produce Lon- 
glnt results, LongInt values are compatible with the Integer type provided 
they are in the Integer range. 

• Arithmetic operations on real-type operands or mixed integer-type and real- 
type operands produce Extended results. Extended values are compatible with 
the Real, Double, and Comp types, provided they are in the range of those 
types. 

• Turbo Pascal implements string- types, which diflFer from the packed-string- 
types defined by ANS Pascal in that they include a dynamic-length attribute 
that may vary during execution. 

• The type compatibility rules are extended to make char-types and packed- 
string-types compatible with string-types. 

• String-type variables can be indexed as arrays to access individual characters 
in a string. 

• The type of a variable-reference can be changed to another type through a 
variable-type-cast. 

• Turbo Pascal implements three new logical operators: xor, shl, and shr. 

• The not, and, or, and xor operators may be used with integer-type operands 
to perform bitwise logical operations. 

• The + operator can be used to concatenate strings. 

• The relational operators can be used to compare strings. 

• Turbo Pascal implements the @ operator, which is used for obtaining the 
address of a variable or a procedure or function. 

• The type of an expression can be changed to another type through a value- 
type-cast. 

• The case statement allows constant ranges in case label lists, and provides an 
optional otherwise part. 

• Procedures and functions can be declared as external (assembly-language sub- 
routines) and inline (inline machine code). 

• A variable parameter can be untyped (typeless), in which case any variable- 
reference may serve as the actual parameter. 

• Turbo Pascal implements units to facilitate modular programming and sepa- 
rate compilation. 
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• Turbo Pascal implements the following file-handling procedures and functions, 
which are not available in ANS Pascal: 

Close Rename Seek FileSize SeekEoln 

Erase lOResult FilePos SeekEof 

• String-type values may be input and output with the Read, ReadLn, Write, 
and WriteLn standard procedures. 

• Turbo Pascal implements two standard devices, Console: and Printer:, and 
furthermore supports user-defined devices. 

• Turbo Pascal implements the following standard procedures and functions, 
which are not found in ANS Pascal: 



Exit 


Int 


ClearScreen 


SizeOf 


Lo 


Halt 


Length 


ClearEOL 


HoveLeft 


Svap 


MeinAvail 


Pos 


DeleteLine 


MoveRight 


HiHord 


MaxAvail 


Concat 


InsertLlne 


FillChar 


LoHord 


Ord^ 


Copy 


GotoXY 


ScanEQ 


SwapWord 


Pointer 


Delete 


KeyPressed 


ScanNE 


Float 


Insert 


ReadChar 


Hi 





Note: Turbo Pascal is unable to detect whether or not a program uses any of 
the extensions listed here. 

Imphmentatiori'Dependent Features 



The eflFect of using an implementation-dependent feature of Pascal, as defined by 
ANSI/IEEE770X3. 97-1983, is unspecified. Programs should not depend on any 
specific path being taken in cases where an implementation-dependent feature is 
being used. Implementation-dependent features include: 

• The order of evaluation of index-expressions in a variable-reference. 

• The order of evaluation of expressions in a set-constructor. 

• The order of evaluation of operands of a binary operator. 

• The order of evaluation of actual parameters in a function call. 

• The order of evaluation of the left and right sides of an assignment. 

• The order of evaluation of actual parameters in a procedure statement. 

• The efiect of reading a text file to which the procedure Page was applied during 
its creation. 

• The binding of variables denoted by the program parameters to entities exter- 
nal to the program. 
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Treatment of Errors 



This section lists those errors from Appendix D of the AN S Pascal Standard that 
are not automatically detected by Turbo Pascal. The numbers referred to here 
are the numbers used in the ANS Pascal Standard. Errors 6, 19-22, and 25-31 
are not detected, because they are not applicable to Turbo Pascal. 

2. If t is a tag-field in a variant-part and/ is a field within the active variant 
of that variant-part, it is an error to alter the value of t while a reference 
to/ exists. This error is not detected. 

3. If p is a pointer variable, it is an error to reference if p is nil. This 
error is not detected. 

4. If p is a pointer variable, it is an error to reference p'^ if p is undefined. 
This error is not detected. 

5. If p is a pointer variable, it is an error to alter the value of p while a 
reference to p^ exists. This error is not detected. 

24. If p is a pointer variable, the procedure call Dispose(p ) is an error if p is 
undefined. This error is not detected. 

42. The function call £o/n(/) is an error if Eqf(f) is True. In Turbo Pascal 
this is not an error, and Eoln(f) is True when Eof(f) is True. 

43. It is an error to reference a variable in an expression if the value of that 
variable is undefined. This error is not detected. 

46, A term of the form i modj' is an error if j is zero or negative. In Turbo 
Pascal, it is not an error if j is negative. 

48. It is an error if a function does not assign a result value to the fiinction 
identifier. This error is not detected. 

51. It is an error if the value of the selector in a case statement is not equal 
to any of the case-constants. In Turbo Pascal, this is not an error; 
instead, the case statement is ignored unless it contains an otherwise 
clause. 



Turbo Pascal Compared to Lisa Pascal 



This section compares Turbo Pascal to Lisa Pascal. Lisa Pascal was the first Pas- 
cal compiler made available by Apple Computer for its line of 68000-based com- 
puters. 
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• Identifier length. In Lisa Pascal, only the first 8 characters of an identifier are 
significant. In Turbo Pascal, the first 63 characters are significant. Lisa Pascal 
does not detect abbreviations and spelling errors ajfter the 8th character; Turbo 
Pascal does. 

• Constant expressions. Lisa Pascal supports constant expressions; that is, 
expressions are allowed where constants are expected, as long as they evaluate 
to a constant value. Turbo Pascal does not support this. 

• Bit packing. Lisa Pascal performs data packing to the bit level. For example, 
in Lisa Pascal, an array variable of the type 

packed array [0. .127] of Boolean 

occupies only 8 bytes, and each of the 8 bits in a byte represent a single 
Boolean component. In Turbo Pascal, data packing is performed only to the 
byte level, so an array variable of the preceding type would occupy 128 bytes. 

• Set limits. In Lisa Pascal, the base-type of a set must not have more than 4088 
possible values, and the ordinal values of the lower and upper bounds must be 
within the range 0. .4087. In Turbo Pascal, the base-type of a set must not have 
more than 256 possible values, and the ordinal values of the lower and upper 
bounds must be within the range 0..255. 

• Type casting. Type casting in Lisa Pascal is more permissive than in Turbo 
Pascal. Specifically, Lisa Pascal allows types other than ordinal-types and 
pointer-types in value- type-casts. For example, assuming the declarations 

type 
Point = record 

x,y: Integer; 
end; 

var 

P: Point; 

then the following statement is allowed in Lisa Pascal, but not in Turbo Pascal: 

P := Point(iaa » t553t + 3E) 

However, the following statement is allowed in both Turbo Pascal and Lisa 
Pascal, since a variable-type-cast may involve any two types as long as they are 
of the same size: 

Longint(P) IflD « t553t + 32; 

• Exponentation operator. Lisa Pascal implements an exponentation operator. 
This operator is not supported by Turbo Pascal. The construct in Lisa 
Pascal is equivalent to Exp{Ln{x) * y) in Turbo Pascal. 

• Short circuit Boolean expressions. Lisa Pascal implements "short circuit" 
Boolean expression evaluation through the operators & (ampersand) and | (ver- 
tical bar). In Lisa Pascal, the following construct is allowed: 

if (p <> nil) & (p*. count = D) then ... 
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In Turbo Pascal, this must be written as 
If p <> nil then if p"". count » D then ... 

• goto statements. In Lisa Pascal, a goto statement may leave the current block, 
that is, a goto statement may jump out of a procedure or a function. This is not 
allowed in Turbo Pascal. 

• cycle and leave statements. These Lisa Pascal statements are not found in 
Turbo Pascal, but they are easily programmed with goto statements. 

• Arbitrary typed functions. Lisa Pascal allows arbitrary typed functions, that 
is, functions that return values of types other than simple-types, string-types, 
and pointer-types. Such functions must be changed to procedures in Turbo 
Pascal. Furthermore, Lisa Pascal allows function results to be treated as vari- 
ables, such as 

FileFlags GetMeiiu(fileID)**.enablePlags; 

In Turbo Pascal, this would require a temporary variable: 

FileMenu GetMenu(filelD) ; 
FileFlags := FileMenu**. enableFlags; 

• Procedural and functional parameters. In Lisa Pascal, procedures and func- 
tions allow procedural and functional parameters; these parameters are not 
allowed in Turbo Pascal. 

• univ parameters. In Lisa Pascal, when a formal parameter is declared with 
the word univ, any actual parameter type is acceptable as long as it has the 
same size as the formal parameter type. Turbo Pascal does not support univ 
parameters, but they are easily circumvented through type casting. Alterna- 
tively, routines that use univ parameters can be reprogrammed to use Turbo 
Pascal's untyped variable parameters, which oflFer greater flexibility. 

• Unit numbers. A Turbo Pascal unit must be given a unit number, which is not 
required in Lisa Pascal. Turbo Pascal stores the interface part of a compiled 
unit using the compiler's internal binary format. This provides for very fast 
processing when the unit is used, but requires a unique unit number for iden- 
tification purposes. Lisa Pascal does not require unit numbers, since the inter- 
face part of a unit is recompiled every time the unit is used (like an include 
file). 

• external routines in units. In Lisa Pascal, when external procedures and func- 
tions are declared in a unit, the procedure and function headers must appear 
in the interface part, and be repeated in the implementation part, followed by 
external directives. In Turbo Pascal, external and inline directives are speci- 
fied along with the procedure and function headers in the interface part, and 
the headers must not be repeated in the implementation part. 

• Segmentation. In Lisa Pascal, segmentation is always enabled. In Turbo Pas- 
cal, a {$S+} directive must be placed in the beginning of a program to enable 
segmentation. 
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• Units and segmentation. In Lisa Pascal, the segment in which a unit is to 
reside is determined by the unit itself, that is, {$S segname} directives in the 
unit determine its segment(s) in the final program. In Turbo Pascal, segment 
directives are ignored in units, and the segment in which a unit ultimately 
resides is determined by {$S segname} directives in the uses-clause of the final 
program. 

• File I/O. Turbo Pascal does not implement the standard procedures Get and 
Put, nor does Turbo Pascal implement file buffer variables; that is, the syntax 

where/ is a file-type variable, is not allowed. Lisa Pascal programs that use 
these features must be changed to use the standard procedures Read and 



• The Close procedure. In Turbo Pascal, the Close procedure does not allow an 
option parameter (such as lock, purge, or crunch). 

• The Exit procedure. In Turbo Pascal, the Exit procedure takes no parameter, 
and can be used only to exit the current block. 

• Standard procedures and functions. The following Lisa Pascal standard proce- 
dures and functions are not implemented in Turbo Pascal: 

Get Release BitNOT ClearBit 
Put HeapResult BitSL 



The bit-manipulation routines are easily coded with Turbo Pascal's not, and, 
or, xor, shl, and shr operators. 

• Compiler directives. The following Lisa Pascal compiler directives are directly 

supported by Turbo Pascal: $D, $1, $R, and $S. The $U directive is also sup- 
ported in Turbo Pascal, but it works differently. The remaining Lisa Pascal 
compiler directives are not supported by Turbo Pascal. In general, it is recom- 
mended that you carefully examine all compiler directives when porting a Lisa 
Pascal program to Turbo Pascal. 



Wnte. 



SetBit 
BitSR 
BitRotL 
BitTest 



BlockRead BitAND 
BlockHrite BitOR 
Mark BitXOR 
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APPENDIX 




Error Messages and Codes 



This appendix lists all the compiler and system error messages, and the lOResult 
and NaN codes. Explanatory notes follow some messages and codes. In some 
cases, solutions are suggested. 



Compiler Error Messages 



Dl ';' expected. 

DE ':' expected. 
D3 expected. 

D< '(' expected. 

D5 ')' expected. 

Ot '=' expected. 

07 ':=' expected. 

Ofi '[ ' expected. 

OR ']' expected. 

10 '.' expected. 

11 '..'expected. 
IE begin expected. 
13 do expected. 

lA end expected. 

15 of expected. 

It interface expected. 

17 then expected. 

Ifl to or downto expected. 

IR inplenentation expected. 

ED Boolean expression expected. 

Bl File variable expected. 

EE Integer constant expected. 

E3 Integer expression expected. 
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5V Integer variable expected. 

E5 Integer or- real constant expected. 

Integer or real expression expected. 

E? Integer or real variable expected. 

Efl Pointer variable expected. 

29 Record variable expected. 

3Q Ordinal type expected. 

All simple types except real types are ordinal types. 

31 Ordinal expression expected. 

35 String constant expected. 

33 String expression expected. 

3< String variable expected. 

35 Identifier expected. 

3(i Type identifier expected. 

3? Field identifier expected. 

The identifier does not denote a field in a recx)rd structure. 

3fl Constant expected, 
3H Variable expected. 

Undefined label. 
Al Unknown identifier. 
<E Undefined type in pointer definition. 

A preceding pointer type definition refers to an unknown type identifier. 

A3 Duplicate identifier. 

The identifier has already been used within the current block. 
AA Type niisfflatch* 
This message means one of the following conditions exists: 

1. incompatible types of the variable and the expression in an assignment 
statement; 

2. incompatible types of the actual and formal parameter in a call to a 
subprogram; 

3. expression type incompatible with index type in array indexing; 

4. incompatible types of operands in an expression. 

AS Constant out of range. 

A{y Constant and case types do not match. 

The type of the case constant is incompatible with the case statement's selec- 
tor expression. 

Al Operand types do not match operator. 

The operator cannot be applied to operands of this type; for example, 'A' 
div '2\ 

At Invalid result type. 
Valid types are all simple types, string types, and pointer types. 
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Invalid string length. 

The lengdi of a string must be in the range 1..255. 
51 Invalid subrange base type. 

All ordinal types are valid base types. 

5E Lower bound greater than upper bound. 
53 Invalid for control variable. 

A for statement control variable must be a single variable defined in the decla- 
ration part of the program or in the declaration part of the current subprogram. 

5^ Illegal assignment. 

1. Files may not be assigned values. 

2. A function identifier can only be assigned values within the statement 
part of the fimction. 

55 String constant exceeds line. 
5tj Error in integer constant. 

The syntax of Integer constants is defined in Chapter 16. Note that whole real 
numbers should be followed by a decimal point and a zero; for example, 
123456789.0. 

57 Error in real constant. 

The syntax of Real constants is defined in Chapter 16. 

5fl Division by zero. 
59 Structure too large. 

The size of a structure may not exceed 32K bytes. 

to Constants are not allowed here. 
t)5 Invalid type cast argument. 

L If a type cast is used in a position where a variable is expected, the 
argument can't be an expression, and the sizes of the argument and the 
result must be identical. 

2. If the type cast argument is an expression, the argument and result 
types must be ordinal types or pointer types. 

3. If the sizes of the argument and the result are not identical, the argu- 
ment and result types must be scalar or pointer types. 

b3 Invalid argument. 

Valid arguments are variables and procedure or fimction identifiers. 

ti4 Label already defined. 
t5 Invalid file type. 

The file type is not supported by the file-handling procedure; for example, 
ReadLn with a typed file or Seek with a text file. 
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fct Cannot read or write variables of this type. 
ti7 Files must be var parameters, 
tft File components may not be files. 

file of file constructs are not allowed. 

70 Set base type out of range. 

The base type of a set must be an enumerated type with no more than 256 
possible values or a subrange with bounds in the range 0..255. 

71 Invalid goto. 

A goto statement in the preceding statement part references a label within a 
for statement from outside that for statement. 

?E Label not within current block. 

A goto statement cannot reference a label outside the current block. 

73 Undefined forward procedure(s) . 

A subprogram has been forward declared in the preceding declaration part, 
but the body never occurred. 

7< program or unit expected. 
75 Error in type. 

This symbol is not a type identifier, nor is it one of the reserved words that 
start a type definition. 

7fe Error in statement. 

This symbol is not a variable, procedure, or label identifier, nor is it one of the 
reserved words that start a statement. 

77 Error. in expression. 

This symbol cannot be used in an expression in the way specified. 
7fl Invalid external definition. 

An object file defines a symbol that is not the identifier of an external declared 
procedure or function. 

7^ Invalid external reference. 

An object file references a symbol that is not the identifier of a variable, proce- 
dure, or function. 

QD Too many symbols. 

Try increasing the symbol table size in the Compile Options Dialog. If the 
syrnbol table size is already set at the 32K byte maximum, divide your program 
or unit into two or more units. 

fll Too many nested scopes. 

The total sum of '"used" units, nested subprograms, and active with statements 
can't exceed 64 at any time. 
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Aa Driver header not found. 

The driver header resource named in the $D compiler directive does not exist. 

fl3 Too many variables. 

The total size of variables declared within the program or within a subprogram 
may not exceed 32K bytes. 

fl< Expression too complicated. 

The code generator ran out of registers. Simplify the expression by breaking it 
into two or more expressions. 

fl5 Segment too large. 

The size of a segment may not exceed 32K bytes. Introduce a new segment or 
move some units or subprograms to another segment. Also, make sure that seg- 
mentation is enabled with a {$SH-} directive in the beginning of the program. 

fit Unit not found. 

This unit is not a resident unit, it is not contained in any of the unit library files 
specified by $U compiler directives, and it has not been compiled to memory in 
a window. 

fl? Duplicate or invalid unit nunber. 

1. This unit has the same reference number as one of the units named 
before it in the uses-clause. 

2. The unit number is not an integer within the range 0 to 32767. 
flfl Unit missing. 

One or more of the units used by this unit have not been named in the uses 
clause. 

h^ Incompatible unit versions. 

One or more of the units used by this unit have been changed since the unit 
was compiled. 

RD Syntax error. 

Rl Unexpected end of text. 

Your program cannot end in its current set-up. It probably has more begins 
than ends. 

S5 Line too long. 

The maximum line length is 128 characters. 

13 Invalid compiler directive. 
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1. The compiler directive letter is unknown. 

2. The compiler directive parameter is invalid. 

3. You are using a global compiler directive when compilation of the body 
of the program has begun. 

Target address found in unit. 

This error is reported by the Compile menu's Find Error command when the 
address at which the execution error occurred is within one of the units used by 
the program. When reporting the error, the compiler also adjusts the target 
address so that the correct statement will be located if you load the source text of 
the unit and issue a new Find Error command. 
HS Undefined external procedure(s) . 

A subprogram has been external declared, but it was not defined by any of the 
object file(s) linked with $L compiler directive(s). 

Rt Object file format error. 

An object file uses an MDS Linker feature which is not supported by Turbo 
Pascal. For further details, please refer to Section 26.4.3. 

S? Runtime support unit missing. 

The unit that defines your predefined procedure or fianction was not named in 
your uses clause; for example, WriteLn without the PasInOut unit. 

9fl Target address not found. 

This error is reported by the Compile menu's Find Error command when the 
address at which the execution error occurred is not within the program itself A 
probable cause is passing invalid parameters to ROM-based system routines. 

«=n Not enough memory. 

This error occurs when the program being compiled is too large to fit in mem- 
ory. Close some windows to free some space, or compile the program to disk. 
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System Error Messages 



This section lists all system errors that may be reported by the Macintosh System 
Error handler. The Compile menu's Find Error command only shows messages 
for system errors 02, 04, 05, 16, 25, 28, and 99. Other errors are not likely to 
occur in a Turbo Pascal program, but they are included here for reference. 

Dl Bus error. 

02 Address error. 

Word or long-word reference was made to an odd address. This typically indi- 
cates use of an uninitialized pointer variable. 

03 Illegal instruction. 
0^ Division by zero. 

A division (div operator) or modulo (mod operator) with a divisor of 0 was 
attempted. 

05 Range check failed. 

An assignment or array indexing operation compiled in the {$R+} state 
involved a value that was not within the allowed range. 

Dt> TrapV exception. 

0? Privilege violation. 

Dfl Trace exception. 

OR Line IDID exception. 

ID Line 1111 exception. 

11 Miscellaneous exception. 

12 Uninpleniented core routine. 

13 Spurious interrupt. 

14 I/O system error. 

15 Segment loader error. 
It Floating point error. 

The halt bit in the floating-point environment word was set. By default, Turbo 
Pascal enables halts for invalid operation, division by zero, and overflow. 

1? Can't load package D. 

24 Can't load package 7. 

E5 Memory allocation error. 

2t Segment loader error. 

2? File map trashed. 

Efl stack overflow error. 

The stack has expanded into the heap. 

32 Memory manager error. 
53 Memory manager error. 
Input/Output check failed. 

A standard I/O procedure compiled in the {$!+} state returned a nonzero 
lOResult 
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lOResuk codes 



This section lists all result cx)des that may be returned by the lOResult function. 
The codes correspond to those returned by the routines in the Macintosh Oper- 
ating System, except for the codes -128, -129, and -130, which are generated 
by Turbo Pascal itself. Although many of the codes are not likely to be returned 
by the lOResult function, they are included here for reference. 

-33 File directory full. 

-3A All allocation blocks on the volume are full. 
-35 Specified volume doesn't exist. 
-3ti Disk I/O error. 

-3? Bad file name or volume name (perhaps zero-length). 
-3fl File not open. 

-3H Logical end-of-file reached during read operation. 
-40 attempt to position before start of file. 
-<1 System heap is full, 
-Ai Too many files open. 
-A3 File not found. 

Volume is locked by a hardware setting. 
-45 File is locked. 

Volume is locked by a software flag. 
-47 One or more files are open. 
-4fi A file with the specified name already exists. 
-4R Only one access path to a file can allow writing. 
-50 No default volume. 
-51 Bad file reference number. 
-53 Volume not on-line. 

-54 Read/write permission doesn't allow writing. 

-55 Specified volume is already mounted and on-line. 

-5t No such drive number. 

-57 Volume lacks Macintosh-format directory. 

-5fl External file system error. 

-S^ Problem during Rename. 

-to Master directory block is bad; must re-initialize volume. 

-tl Read/write permission doesn't allow writing. 

-IDA Not enough room in heap zone. 

-lED Directory not found. 

-lEl Too many working directories open. 

-lEE Attempted to move into offspring. 

-123 Attempt to do HFS operation on non-HFS volume. 

-127 Internal file system error. 

-lEfl Textfile not open for input. 

-129 Textfile not open for output. 

-130 Error in numeric value during read from textfile. 
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NaN codes 



when a floating-point operation cannot produce a meaningful result, the opera- 
tion delivers a special bit pattern called a NaN (Not a Number). For example, 0 
divided by 0 yields NaN (004), The following NaN codes may be reported. 

DOl Invalid square root/ such as Sqrt(-l). 

DDE Invalid addition or subtraction, such as INF - INF. 

DD< Invalid division/ such as D / 0. 

DDfi Invalid multiplication/ such as D * INF. 

DQ9 Invalid remainder or mod/ such as x rem D. 

D17 attempt to convert invalid ASCII string to binary. 

DED Result of converting comp NaN to floating.. 

D21 attempt to create NaN with a zero code. 

D33 Invalid argument to trig routine. 

D3^ Invalid argument to inverse trig routine. 

D3t Invalid argument to log routine. 

D37 Invalid argument to x*i or x*y routine. 

Q3fl Invalid argument to financial function. 

ESS Oninitialized storage. 
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APPENDIX 



Compiler Directives 



Some of the Turbo Pascal compilers features are controlled through compiler 
directives. A compiler directive is introduced as a comment with a special syntax; 
Turbo Pascal allows compiler directives wherever comments are allowed. 

A compiler directive starts with a $ character as the first character after the 
opening comment delimiter. The $ is immediately followed by a letter that desig- 
nates the particular directive. 

There are two types of directives: switch directives and parameter directives. 
A switch directive turns a particular compiler feature on or off by specifying + or 
— immediately after the directive letter. A parameter directive is followed by a 
string, such as a file name or a segment name. The string argument is terminated 
by the closing comment delimiter. 

Compiler directives are either global or local. Global directives affect the 
entire compilation, whereas local directives affect only the part of the compila- 
tion that extends from the directive until the next occurrence of the same direc- 
tive. Global directives must appear before the declaration part of the program or 
the unit being compiled; that is, before the first uses, label, const, type, proce- 
dure, function, or begin keyword of a program or before the interface keyword 
of a unit. Local directives, on the other hand, may appear anywhere in the 
program or unit. 
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Examples of compiler directives follow: 
{$B+} 

{$R- Turn off range checking) 
{$1 TypeDefs.Pas} 
{$U Turbo: Units iMacLibrary} 
m ftPPLMYED} 

Set Bundle Bit 

Syntax: {$B+} or {$B-} 
Default: {$B-} 
Type: Global 

This switch controls the bundle-bit setting in the compiled application file. 
You should only set the bundle bit if your application's resource file contains a 
BNDL resource (see the R parameter directive). The B switch only takes efiect if 
the compiler was invoked with the Compile To Disk command. 

Generate Debug Symbols 

Syntax: {$D+} or {$D-} 
Default: {$D-} 
Type: Local 

This switch turns the generation of procedure names in the object code on or 
off. Debug symbols allow you to see the names of your procedures when you 
debug your program, using MACSBUG, for instance. 

Compile Desk Accessory 

Syntax: {$D PasDeskAcc} 
Type: Global 

The appearance of this parameter directive tells the compiler that you are 
compiling a desk-accessory program. Instead of generating CODE resources in 
the output file, the compiler generates a DRVR resource with a resource ID of 
12. The D directive also has the effect of turning off segmentation (corresponding 
to a {$S-} directive) and changing the output file type to DFIL and the output file 
creator to DMOV (corresponding to a {$T DFILDMOV} directive). The latter 
causes the FINDER to display the desk-accessory icon for the generated file and 
to launch the FONT/DA MOVER when the file is double-clicked. For fiirther 
details on compiling desk accessories, refer to Chapter 10. 
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Check I/O Results 



Syntax: {$I+}or{$I-} 
Default: {$!+} 
Type: Local 

This switch turns on or oflF the automatic generation of code that checks the 
I/O result of a call to an I/O procedure from the PasInOut unit. If an I/O proce- 
dure returns a non-zero I/O result when this switch is on, the program termi- 
nates by displaying the system error bomb box with an ID of 99. When this 
switch is oflF, it is up to you to check for I/O errors through the lOResult function. 

Include File 

Syntax: {$1 FileName} 
Type: Local 

This parameter directive instructs the compiler to include the named file in 
the compilation. In eflFect, the file is inserted in the compiled text after the line 
containing the Include directive. If FileName does not specify a directory, the 
program searches for the file in the directory specified by the $1 entry of the 
Compile Options Dialog, or in the current directory if the $1 entry is empty. 

Link Object File 

Syntax: {$L FileName} 
Type: Local 

This parameter directive instructs the compiler to link the named file with the 
program or unit being compiled. The L directive is typically used to link code 
written in another language (for example, the MDS assembler) for subprograms 
declared to be external. The named file must be an MDS object-format .REL 
file. Files named in L directives are always linked into the blank segment, that is, 
the segment that also contains the main statement part. A program or unit may 
contain multiple L directives, but all of them must appear before the begin 
keyword that heads the main statement part. If FileName does not specify a 
directory, the program searches for a file in the directory specified by the $L 
entry of the Compile Options Dialog, or in the current directory if the $L entry 
is empty. 
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Define Output File 



Syntax: {$0 FileName} 
Default: {$0 ProgName} 
Type: Global 

This parameter directive defines the name of the output file generated by the 
Compile to Disk command. The default output file name PROGNAME is the 
name of the program or unit; that is, the name specified after the program or 
unit keyword. If the output file of a unit you are compiling already exists, and if it 
contains a unit of the same name, the new unit replaces the older version stored 
in the file. If FileName specifies a directory, the file is created in that directory. 
Otherwise, the output file is created in the directory specified by the $0 entry in 
the Compile Options Dialog, or in the current directory if the $0 entry is empty. 

Generate Range Checks 

Syntax: {$R+} or {$R-} 
Default: {$R-} 
Type: Local 

This switch instructs the compiler to turn the generation of range checking 
code on or off. When range checking is on, all array and string indexing expres- 
sions are checked to be within the defined bounds, and all assignments to scalar 
and subrange variables are checked to be within range. If a range check fails, the 
program terminates by displaying the system error bomb box with an ID of 5. 

Define Resource File 

Syntax: {$R FileName} 
Type: Global 

The appearance of this parameter directive indicates to the compiler that your 
program uses the resources stored in the named file. The file is typically a .RSRC 
file generated from a .R file by the resource compiler (RMAKER). If the com- 
piler was invoked using the Compile to Disk command, all resources stored in 
the named file are copied to the output file. If the compiler was invoked using 
the Compile to Memory command, the named file will automatically be opened 
when the program is executed by a Compile Run command. If FileName does 
not specify a directory, the file is searched for in the directory specified by the $R 
entry of the Compile Options Dialog, or in the current directory if the $R entry 
is empty. 
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Generate Segmented Code 



Syntax: {$S+} or {$S-} 
Default: {$S-} 
Type: Global 

This switch instructs the compiler to turn the generation of segmented code 
on or off. When segmentation is off (the default state), the size of the generated 
code cannot exceed 32K, which is the maximum size of a single segment. Seg- 
mentation is always off when compiling a unit or a desk accessory, so the com- 
piled code of a unit or a desk accessory cannot be larger than 32K. When 
segmentation is turned on with a {$S -f } directive, there is no limit to the size of a 
program, as long as its code is divided into segments of less than 32K using the 
$S parameter directive. When segmentation is off, all subprogram calls and sub- 
program address references are coded using PC-relative instructions. When seg- 
mentation is on, all calls and address references are routed through the segment 
loader jump table. 

Define Segment Name 

Syntax: {$S SegName} 
Default: {$S } 
Type: Local 

This parameter directive defines the name of the segment in which the code of 
the following units or subprograms is to be stored. The $S parameter directive is 
ignored when compiling units and desk accessories; for programs, it only takes 
effect when segmentation has been enabled with a {$S +} directive. SegName is a 
string of up to eight case-sensitive characters. If less than eight characters are 
specified, the remaining characters are assumed to be blanks. If the specified 
segment does not exist, a new segment is created. The default segment, also 
called the blank segment, is a segment whose name consists of eight blanks. 

Note: Segment names only exist within the compiler; in the finished code they 
are turned into code resource numbers starting from 1. 
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Define Type and Creator 



Syntax: {$T ttttccxjc} 
Default: {$TAPPL????} 
Type: Global 

This parameter directive is used to define the type and creator of an applica- 
tion file generated by the Compile to Disk command. The first four characters of 
the string argument define the type; the next four characters define the creator 
(note that no separators are placed between the two definitions). The T directive 
is typically used in connection with the B switch and a resource file that contains 
a bundle (BNDL) resource. 

Use Standard Units 

Syntax: {$U-f } or {$U-} 
Default: {$U+} 
Type: Global 

This switch determines whether or not the standard units PasInOut and 
FasConsole should be included in the compilation. In eflPect, the default {$U+} 
directive corresponds to inserting uses PasInOut /PasConsole before the declara- 
tion part of the program or unit being compiled. 

Note: The PasSystem unit is always included in a compilation regardless of the 
U switch. The PasPnnter unit is never included automatically. 

Search Unit Library 

Syntax: {$U FileName} 
Type: Global 

This parameter directive is used to specify the name of a unit library file to 
search for, in addition to the resident units installed in Turbo itself If FileName 
specifies a directory, the unit library file is opened in that directory. Otherwise, 
the unit library file is opened in the directory specified by the $U entry in the 
Compile Options Dialog, or in the current directory if the $U entry is empty. 

When searching for a unit named in a uses-clause, Turbo Pascal first inspects 
all open windows that contain a unit that has been compiled to memory. Next, it 
searches all unit library files named in U directives in order of appearance. 
Finally, it looks to itself to see if the unit is installed as a resident unit. 

If a unit library file is named in both the O and U directives (which may be the 
case when compiling a unit), the U directive naming the file must be the first U 
directive. 
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APPENDIX 



Macintosh Interface Units 



The following pages contain the 15 Macintosh interface units used by Turbo 
Pascal. Below each head is a brief explanation of what the unit is and what it can 
do, followed by the inter&ce listing. The units are discussed in this order: 

• PasInOut 

• PasConsole 

• PasPrinter 

• SANE 

• MemTypes 

• QuickDraw 

• OSIntf 

• Toollntf 

• Packlntf 

• MacPrint 

• FixMath 

• GrafiD 

• AppleTalk 

• Speechlntf 

• SCSIIntf 
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PasInOut 



PasInOut implements the standard Pascal input/output (I/O) routines {Read, 
ReadLn, Writer WriteLn, Reset, Rewrite, and so on), as well as the Turbo Pascal- 
specific ones (Close, Seek, Rename, Erase, and so forth). It also does all I/O and 
range-error checking. If you look at the interface listing below, you'll find that 
there is very little you can use directly; instead, the compiler makes calls to 
specific hidden routines in the implementation, 
wit PasInOut(-2); { PasInOut - standard I/O unit > 
interface 
Tar 

TextType , TextCreator , 

FileType,FileCreator: packed array Cl..'^] of Char; 
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VasComde 



PasConsole is the unit that makes it easy to write textbook Pascal programs. It 
creates a window that emulates a terminal screen 80 characters wide by 25 lines 
deep. When this unit is used by a program or unit, any calls to Read or ReadLn 
are made from the keyboard and automatically echoed to this window; likewise, 
any calls to Write or WriteLn write to this window. A number of cursor- and 
screen-control routines are available: ClearScreen, ClearEOL, InsertLine, 
DeleteLine, and GoToXY. The functions KeyPressed and ReadCharaxe included, 
as are the file variables Input and Output. This unit also creates a new device 
(Console:) that can be assigned to any file of type text. The user can then send 
output to the screen (instead of to a disk file). 

unit PasConsole (-3); { PasConsole - console unit } 

interface 

ases PaslnOut; 

?ar 

Input, Output: Text; 

fanction KeyPressed: Boolean; external; 
function ReadChar: Char; external; 

procedure ClearScreen; external; 
procedure ClearEOL; external; 
procedure InsertLine; external; 
procedure DeleteLine; external; 
procedure GotoXT(X,Y: Integer); external; 
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PasPrinter 



PasPrinter declares the text-file variable Printer and connects it to a device 
driver that allows you to send standard Pascal output to the printer using Write 
and WriteLn. 

Like PasConsohy this unit creates a new device (Printer:) that can be assigned 
to any file of type text; it will then send output to the printer (instead of to a disk 
file). 

unit PasPrinter (-^); { PasPrinter - printer unit } 

Interface 

uses PasInOut; 

Tar 

Printer: Text; 
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SANE 



The SANE unit implements the Standard Apple Numeric Environment. SANE 
is the basis for all floating-point mathematical calculations performed by Turbo 
Pascal Programmers who are interested in using SANE features not directly 
supported by Turbo Pascal can access these features through the SANE unit. For 
detailed instructions about SANE, see Chapter 26 and the Apple Numerics 
Manual 

nnlt SANE (-5); 

{ SANE - Standard Apple Numeric Environnient interface unit } 

{ Implements floating-point operations not directly supported > 
{ by Turbo Pascal > 

interface 

const 



DecStrLen 
SigDigLen 

Invalid 

Underflow 

Overflow 

DivByZero 

Inexact 

type 

DecStr 

CStrPtr 

Decimal 



DecForm 

RelOp 

NumClass 

Exception 

RoundDir 

RoundPre 

Environment 



E55; 
EQ; 

- 1 

- E 
= ^ 

- fl 
= It, 



= String [DecStrLen]; 

= *Char; 

= record 

sgn : D..1; 
exp : Integer; 
sig : string[ SigDigLen] 
end; 

= record 

Style : ( FloatDecimal, FixedDecimal ); 

Digits : Integer; 
end; 

= ( GreaterThan, LessThan, EqualTo, Unordered ); 

= ( SNaN, QNaN, Infinite, ZeroNum, NormalNum, DenormalNum ); 

* Integer; 

= ( ToNearest/ Upward, Downward, TowardZero ); 
= ( ExtPrecision, DblPrecision, RealPrecision ); 
= Integer; 



function NumEInteger 
function NumELongint 
function NumEReal 



( X : Extended ) : Integer; external; 
( x ; Extended ) : Longlnt; external; 
( X : Extended ) : Real; external; 
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function Nui!i5Double ( x : Extended ) : Double; external; 
function NumSExtended ( x : Extended ) : Extended; external; 
function NuniEConip ( x : Extended ) : Conp; external; 

?rocedure NaniBDec ( var f : DecForm; x : Extended; var d : Decliaal ); external; 
unction DecENum ( d : Decimal ) : Extended; external; 
procedure NundStr ( f : DecForm; x : Extended; var s : DecStr ); external; 
function StrENum ( s : DecStr ) : Extended; external; 

function Remainder ( X/ y : Extended; 7ar quo : Integer) : Extended; external; 

function Rint ( x : Extended ) : Extended; external; 

function Scalb ( n : Integer; x : Extended ) : Extended; external; 

function Logb ( x : Extended ) : Extended; external; 

function CopySign ( x, y : Extended ) : Extended; external; 



function 
function 
function 

function 
function 
function 
function 
function 
function 
function 
function 
function 
function 

function 
function 
function 
function 

function 
function 

Procedure 
unction 

procedure 
function 

procedure 
function 

Procedure 
unction 

procedure 
procedure 

procedure 
procedure 

function 
procedure 



NextReal ( x, y : Real ) : Real; external; 
NextDouble ( x, y : Double ) : Double; external; 
NextExtended { x, y : Extended ) : Extended; external; 



LogE { X : Extended ) : Extended 

Lnl ( X : Extended ) : Extended 

ExpE ( X : Extended ) : Extended 

Expl ( X : Extended ) : Extended 

Xpwrl ( X : Extended; i : Integer ) : Extended 

XpwrY ( x, y : Extended ) : Extended 

Compound ( r, n : Extended ) : Extended 

Annuity ( r, n : Extended ) : Extended 

Tan ( X : Extended ) : Extended 
RandomX ( var x : Extended ) 



external 
external 
external 
external 
external 
external 
external 
external 
external 



ClassReal ( x : Real ) 
ClassDouble ( x : Double ) 
ClassComp ( x : Comp ) 
ClassExtended ( x : Extended ) 



: Extended; external; 

: NumClass; external; 
: NumClass; external; 
: NumClass; external; 
NumClass; external; 



SignNum ( x : Extended ) : Integer; external; 
NAN ( i : Integer ) : Extended; external; 

SetException ( e : Exception; b : Boolean ); external; 
TestException ( e : Exception) ; Boolean; external; 

SetHalt ( e : Exception; b : Boolean ); external; 
TestHalt ( e : Exception) : Boolean; external; 

SetRound ( r : RoundDir ); external; 
GetBound : RoundDir; external; 

SetPrecision ( p : RoundPre ); external; 
GetPrecision : RoundPre; external; 

SetEnvironment { e : Environment ); external; 
GetEnvironment ( var e : Environment ); external; 

ProcEntry { var e : Environment ); external; 
ProcExit ( e : Environment ); external; 

GetHaltVector : Longint ; external; 
SetHaltVector { v : Longint ) ; external; 



function Relation ( X/ y : Extended) : Relop; external; 
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MemTypes 



MemTypes defines special Mac data types, such as SignedByte, Ptr, Handle ^ and 
Str255. That's all it does; it doesn't define any constants, variables, or routines. 
It is used by every unit in this list and must be in any Mac-style application. 

unit HenTypesl-b) ; 

l&terface 

type 



SignedByte * -12fl..lE7; { any byte in memory > 

Byte « D..E55; { unsigned byte for fontmgr > 

Ptr » *SignedByte; { blind pointer > 

Handle = *Ptr; { pointer to a master pointer > 

ProcPtr * Ptr; { pointer to a procedure > 

Fixed * Longint; { fixed point arithmetic type > 

StrE55 = String[255]; { maximum string size > 

StringPtr = *Str255; { pointer to maximum string > 



StringHandle » ^StringPtr; { handle to maximum string } 
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QuickDraw 



QuickDraw is a Macintosh graphics package that lets you perform complex 
graphic operations quickly and easily. This unit defines all the constants, types, 
variables, procedures, and functions needed to use QuickDraw. 
unit QuickDraw (-?); 
interface 



nses NenTypes; 

const srcCopy 
srcOr 
srcXor 
srcBic 
notSrcCopy 
notSrcOr 
notSrcXor 
notSrcBic 
patCopy 
patOr 
patXor 
patBic 
notPatCopy 
notPatOr 
notPatXor 
notPatBic 



0; {the liti transfer modes > 

= 1 

= 2 

= 3 

= 5 

= E, 

= 7 



= 9 
= ID 
= 11 

- IE 

- 13 

= 15 



{ QuickDraw color separation constants } 



normalBit 


= D; 


inverseBit 


i; 


redBit 


« 


greenBit 


= 3; 


blueBit 


= 2; 


cyanBit 


a; 


magentaBit 


= ?; 


yellowBit 


= t; 


blackBit 


5; 


blackColor 


33; 


whiteColor 


- 30; 


redColor 


= 205; 


greenColor 


= 3<1; 


blueColor 


= 409; 


cyanColor 


= 273; 


magentaColor 


= 137; 


yellowColor 


= tR; 


picLParen 


= D; 


picRParen 


' 1; 



{ normal screen mapping > 
{ inverse screen mapping > 
{ RGB additive mapping > 



{ CMYBk subtractive mapping } 



{ colors expressed in these mappings } 



{ standard picture comments > 



type QDByte 
QDPtr 
QDHandle 
Pattern 
Bitslt 
VHSelect 
GrafVerb 
Styleltem 



{ blind pointer > 
} 



SignedByte; 
Ptr; 

Handle; { blind handle 

packed array[0..7] of D..255; 
array [0.. 15] of integer; 

(v,h); 

( frame , paint , erase , invert , f ill ) ; 

{bold, italic, underline/Outline, shadow, condense/extend); 
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style « set of Styleltem; 

Fontlnfo = record 

ascent: Integer; 
descent: Integer; 
widMax: Integer; 
leading: Integer; 
end; 

Point - record case Integer of 
0: (v: Integer; 

h: Integer); 
1: (vh: array [VHSelect] of Integer); 
end; 

Rect = record case Integer of 
D: (top: Integer; 

left: Integer; 

bottom: Integer; 

right: Integer); 
1: (topLeft: Point; 

botRight: Point); 

end; 

BitMap « record 

baseAddr: Ptr; 
rowBytes: Integer; 
bounds: Rect; 
end; 

Cursor = record 

data: Bitslt; 
mask: BitsKi; 
hotSpot: Point; 
end; 

PenState « record 

pnLoc: Point; 
pnSize: Point; 
pnMode: Integer; 
pnPat: Pattern; 
end; 

PolyHandle = "PolyPtr; 
PolyPtr - ^Polygon; 
Polygon - record 

polySize: Integer; 

polyBBox: Rect; 

polyPoints: array [0..D1 of Point; 
end; 



RgnHandle = "RgnPtr; 
RgnPtr = "Region; 
Region * record 

rgnSize: Integer; { rgnSize = ID for rectangular > 

rgnBBox: Rect; 

{ plus more data if not rectangular > 
end; 



PicHandle = *PicPtr; 
PicPtr * "Picture; 
Picture = record 

picSize: Integer; 

picFrame: Rect; 
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{ plus byte codes for picture content > 
end; 



QDProcsPtr = •QDProcs; 
QDProcs " record 

textProc: Ptr; 

lineProc: Ptr; 

rectProc: Ptr; 

rRectProc: Ptr; 

ovalProc: Ptr; 

arcProc: Ptr; 

polyProc: Ptr; 

rgnProc: Ptr; 

bitsProc: Ptr; 

connentProc: Ptr; 

txMeasProc: Ptr; 

getPicProc: Ptr; 

putPicProc: Ptr; 
end; 



GrafPtr 
GrafPort 



7ar thePort: 
white: 
black: 
gray: 
ItGray: 
dkGray: 
arrow: 



*GrafPort; 

record 
device: 
portBits: 
portRect: 
visRgn: 
clipRgn: 
bkPat: 
fillPat: 
pnLoc: 
pnSize: 
pnHode: 
pnPat: 
pnVis: 
txFont: 
txFace: 
txMode: 
txSize: 
spExtra: 
fgColor: 
bkColor: 
colrBit: 
patStretch : 
picSave: 
rgnSave: 
polySave: 
grafProcs: 

end; 

GrafPtr; 
Pattern; 
Pattern; 
Pattern; 
Pattern; 
Pattern; 
Cursor; 



Integer; 

BitMap; 

Rect; 

RgnHandle; 

Rgnflandle ; 

Pattern; 

Pattern; 

Point; 

Point; 

Integer; 

Pattern; 

Integer; 

Integer; 

Style; 

Integer; 

Integer; 

Fixed; 

LongInt; 

Longint; 

Integer; 

Integer; 

Handle; 

Handle; 

Handle; 

QDProcsPtr; 



screenBits: BitMap; 
randSeed: Longint; 



{ GrafPort routines > 



procedure initGraf 
procedure OpenPort 
procedure InitPort 
procedure ClosePort 
procedure SetPort 



(globalPtr: Ptr); 
(port: GrafPtr); 
(port: GrafPtr); 
(port: GrafPtr); 
(port: GrafPtr); 



inline $AflbE; 
inline $Aflt,F; 
inline $AflbD; 
inline $Afl7D; 
inline $Afi73; 
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procedure ClosePort {port: GrafPtr); 
procedure SetPort (port: GrafPtr); 
procedure GetPort (var port: GrafPtr); 
procedure GrafDevice (device: Integer); 
procedure SetPortBits(bni: BitMap); 
procedure PortSize (width, height: Integer); 
procedure MovePortTo (leftGlobalrtopGlobal: Integer); 
procedure SetOrigin (h,v: Integer); 

(rgn: RgnHandle); 
(rgn: RgnHandle); 
(r: Sect); 
(pat: Pattern); 



procedure SetClip 
procedure GetClip 
procedure ClipBect 
procedure BackPat 



{ Cursor routines > 

procedure InitCursor; 
procedure SetCursor(crsr: Cursor); 
procedure HideCursor; 
procedure ShowCursor; 
procedure ObscureCursor; 

{ Line routines } 



Inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 



$llfl7D 
$Afl73 
$Rfl74 
$Afi7E 
$Afl75 
$Afl7(> 
$Afl77 
$A&7fl 
$Afl7q 
$Afl7A 
$Aa7B 
$Afl7C 



inline $Afl50; 
inline $Afl51; 
inline $Afi52; 
inline $Afi53; 
inline $Afi5(,; 



procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 



HidePen; 
ShowPen; 
GetPen 
GetPenState 
SetPenState 
PenSize 
PenMode 
PenPat 
PenNormal; 
MoveTo 
Hove 
LineTo 
Line 



(var pt: Point); 
(var pnState: PenState); 
(pnState: PenState); 
(width, height: Integer); 
(mode: Integer); 
(pat: Pattern); 

(h,v: Integer); 
(dh/dv: Integer); 
(h,v: Integer); 
(dh,dv: Integer); 



{ Text routines } 

procedure TextFont 
procedure TextFace 
procedure TextMode 
procedure TextSize 
procedure SpaceExtra 
procedure DrawChar 
procedure Drawstring 
procedure DrawText 
function CharWidth 
function Stringtfidth 



(font: Integer); 
(face: Style); 
(mode: Integer); 
(size: Integer); 
(extra: Fixed); 
(ch: Char); 
(s: Stra55); 



inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 



$AflR7 

$Aflqfi 
$Aflqq 

lAfiSB 

$Aflqc 
$AflqD 
$AfiqE 
$Aflq3 
$Aflq< 
$Aflqi 
$AflqE 



inline $Afifi7; 
inline $Ea5F,$lDia/$BFDDi 

inline $Aflflq; 

inline $AfifiA; 

inline $AflflE; 

inline $Aflfi3; 

inline $Aflfl^; 



$Aflfifl; 



(textSuf: Ptr; firstByte,byteCount: Integer); inline $Aflfl5; 



(ch 
(s: 



Char): Integer; 
S trass ): Integer; 



function TextHidth (textBuf: Ptr; firstByte/byteCount: 
procedure GetFontlnfo (var info: Fontlnfo) ; 



inline SAflflD; 
inline SAflflC; 
Integer): Integer; 

inline SAflflB; 



inline SAaflt; 



procedure MeasureText (count: Integer; textAddr, charLocs: Ptr); inline $Aa37; 
{ point calculations > 



procedure AddPt (src: Point; var dst: Point); inline $Afl7E; 

procedure SubPt (src: Point; var dst: Point); inline $Afl7F; 

?rocedure SetPt (var pt: Point; h,v: Integer); inline $AflftQ; 

unction EqualPt (ptl,ptE: Point): Boolean: inline $Afl51; 

procedure ScalePt (var pt: Point; fromRectrtoRect: Rect); inline $AflFfl; 
procedure MapPt (var pt: Point; fromRect,toRect: Rect) ; inline $AflFq; 
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procedure LocalToGlobal (var pt: Point); 
procedure GlobalToLocal (var pt: Point); 



inline $flfi7D; 
inline $AA71; 



{ rectangle calculations } 

Procedure SetRect {var r: 
nnction EqualRect ( recti, rectE: rect): Boolean; 
fnnction EmptyRect (r: rect): Boolean; 
procedure Off setRect (var r: Rect; dh,dv: Integer); 
procedure HapRect (var r: Rect; fromRect^toRect: 
procedure InsetRect (var r: Rect; dh,dv: Integer); 



function SectRect 
procedure UnionRect 
function PtInRect 
procedure PtERect 



Rect; left, top, right, bottom: Integer); inline SAflA?; 
" inline $AflAt; 

inline $AfiAE; 
inline $A&Afl; 
Rect); inline $AflFA; 

inline $AflAR; 



(srcl,srcE: Rect; var dstRect: Rect): Boolean; inline $AflAA; 
(srcl,src2: Rect; var dstRect: Rect); inline $AflAB; 

(pt: Point; r: Rect): Boolean; inline $AflAD; 
{ptl,pt5: Point; var dstRect: Rect); inline $AflAC; 



{ graphical operations on rectangles > 



procedure FrameRect 
procedure PaintRect 
procedure EraseRect 
procedure InvertRect 
procedure FillRect 



(r: Rect); 

(r: Rect); 

(r: Rect); 

(r: Rect); 

(r: Rect; pat: Pattern); 



inline $AaAl; 
inline $AaA5; 
inline $AflA3; 
Inline $AflA^; 
inline. $AflA5; 



{ RoundRect routines } 



procedure FrameRoundRect (r: Rect; ovffd,ovHt: Integer); inline $AflfiD; 

procedure PaintRoundRect (r: Rect; 07Hd,ovHt: Integer); inline $AflBl; 

procedure EraseRoundRect (r: Rect; ovtfd,ovHt: Integer); inline $AflBE; 

procedure InvertRoundRect (r: Rect; ovWd,ovHt: Integer); inline $AaB3; 
procedure FillRoundRect (r: Rect; ovffd,ovHt: Integer; pat: Pattern); inline $AflB<; 

{ oval routines > 

procedure FrameOval (r: Rect); inline $AflB7; 

procedure PaintOval (r: Rect); inline $AflBfl; 

procedure EraseOval (r: Rect); inline lAflBR; 

procedure InvertOval (r: Rect); inline $AA6A; 

procedure FillOval (r: Rect; pat: Pattern); inline lAflBB; 



{ arc routines } 

procedure FrameArc 
procedure PaintArc 
procedure EraseArc 
procedure InvertArc 



(r: Rect; startAngle,arcAngle: Integer); inline $AfiBE; 

(r: Rect; startAngle,arcAngle: Integer); inline $AflBF; 

(r: Rect; startAngle,arcAngle: Integer); inline $AaC0; 

(r: Rect; startAngle,arcAngle: Integer); inline $Aaci; 



procedure FillArc (r: Rect; startAngle,arcAngle: Integer; pat: Pattern); inline $AaCE; 
procedure PtToAngle (r: Rect; pt: Point; var angle: Integer); inline $AaC3; 
{ polygon routines.} 



function OpenPoly: 
procedure ClosePoly; 
procedure KillPoly 
procedure OffsetPoly 
procedure MapPoly 
procedure FramePoly 
procedure PaintPoly 



PolyHandle; 

(poly: PolyHandle); 

(poly: PolyHandle; dh,dv: Integer); 

(poly: PolyHandle; fromRect/toRect: Rect); 

(poly: PolyHandle); 

(poly: PolyHandle); 



inline $AflCB; 
inline $AacC; 
inline $AacD; 
inline $AaCE; 
inline $AflFC; 
inline SAfiCt; 
inline $AflC7; 
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procedure ErasePoly (poly: PolyHandle); inline $RflCfl; 

procedure InvertPoIy (poly: PolyHandle); inline $aacS; 

procedure FillPoly (poly: PolyHandle; pat: Pattern); inline $ftfiCR; 

{ region calculations > 



function 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

function 

function 

function 

function 



NewRgn: RgnHandle; inline 
DisposeRgn(rgn: RgnHandle); inline 
CopyRgn (srcRgnrdstRgn: RgnHandle); inline 
SetEinptyRgn(rgn: RgnHandle); inline 
SetRectRgn(rgn: RgnHandle; lef t / top , right, bottom: Integer); 

inline 
inline 
inline 
inline 
; inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 
inline 



RectRgn (rgn: RgnHandle; r: Rect); 
OpenRgn; 

CloseRgn (dstRgn: RgnHandle); 

OffsetRgn (rgn: RgnHandle; dh,d7: Integer); 

MapRgn (rgn: RgnHandle; froiRectftoRect: R 

InsetRgn (rgn: RgnHandle; dh,d7: Integer); 

SectRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle); 

UnionRgn (srcRgna,srcRgnB, dstRgn: RgnHandle); 

DiffRgn (srcRgnR,srcRgnB, dstRgn: RgnHandle); 

XorRgn (srcRgnR,srcRgnB, dstRgn: RgnHandle); 

EqualRgn (rgnft/ignB: RgnHandle): Boolean; 

EmptyRgn (rgn: RgnHandle): Boolean; 

PtInRgn (pt: Point; rgn: RgnHandle): Boolean; 

RectlnRgn (r: Rect; rgn: RgnHandle): Boolean; 



$AQDfl; 
%Km; 
$AflDC; 
$&flDD; 

inline $&flDE; 
$AflDF; 
$AADA 
$AflDB 
$AQEQ 
lAflFB 
$A6E1 

$mA 

$AfiE5 
$AfiEt, 
$AflE7 
$AfiE3 
lAflEE 
$AflEfl 

$AaEq 



{ graphical operations on regions > 



procedure FrameRgn 
procedure PaintRgn 
procedure EraseRgn 
procedure InvertRgn 
procedure FillRgn 



(rgn: RgnHandle); 

(rgn: RgnHandle); 

(rgn: RgnHandle); 

(rgn: RgnHandle); 

(rgn: RgnHandle; pat: Pattern); 



inline $AflD2 
inline SAflDB 
inline $AflD4 
inline $AAD5 
inline $AflD{3 



{ graphical operations on BitHaps > 



procedure ScrollRect(dstRect: Rect; dh,dv: Integer; updateRgn: rgnHandle); inline 

$AfiEF; 

procedure CopyBits (srcBits,dstBits: BitMap; 

srcRect/dstRect: Rect; 
mode: Integer; 

maskRgn: RgnHandle); inline $AflEC; 

procedure SeedFill ( srcPtr , dstPtr : Ptr ; 

srcRow / dstRotf I height , words : Integer ; 
seedH/seedV: Integer); inline $A&3R; 

procedure CalcMask ( srcPtr , dstPtr : Ptr; 

srcRow/dstRow, height, words: Integer); inline $Afi3fl; 
procedure Copy Mask (srcBits,inaskBits# dstBits: BitMap; srcRect,iiiaskRect/dstRect: rect); 

inline $Afil7; 

function GetMaskTable: Ptr; inline $Afi3t,$dEfifi; 



{ picture routines } 



function OpenPicture(picFraiie: Rect): PicHandle; inline $AflF3; 

procedure ClosePicture; inline $AflF<; 

procedure DrawPicture(niyPicture: PicHandle; dstRect: Rect); inline $AflFt; 
procedure PicConinient(kind,dataSize: Integer; dataHandle: Handle); inline $AflFE; 
procedure KillPicture(myPicture: PicHandle); inline $AaF5; 

{ the bottleneck interface > 

procedure SetStdProcs(Tar procs: QDProcs); inline $AflEA; 

procedure StdText (count: Integer; textAddr: Ptr; nuiiier,denoin: Point); inline $Aflfl2; 
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proceflttre StdLine (newPt: Point); ialine $AflSO; 

procedure StdRect (verb: Graf Verb; r: Rect); inline SAfiAO; 

procedure StdRRect (verb: GrafVerb; r: Rect; 07M,ovHt: Integer); inline lAflAF; 
procedure StdOval (verb: GrafVerb; r: Rect); inline $AflBt; 

procedure StdArc (verb: GrafVerb; r: Rect; startAngle/arcAngle: Integer); inline $AflBD; 

procedure StdPoly (verb: GrafVerb; poly: PolyHandle); inline $AflC5; 

procedure StdRgn (verb: GrafVerb; rgn: RgnHandle); inline $AflDl; 
procedure StdBits (var srcBits: BitMap; var srcRect,dstRect: Rect; mode: 

Integer; maskRgn: RgnHandle); inline SAAEB; 
procedure StdCoiiinient (kind/dataSize: Integer; 

dataHandle: Handle); inline $AflFl; 
function StdTxMeas (count: Integer; textAddr: Ptr; 

var nunier,denoin: Point; 

var info: Fontlnfo): Integer; inline $AflED; 

procedure StdGetPic (dataPtr: Ptr; byteCount: Integer); inline $AflEE; 

procedure StdPutPic (dataPtr: Ptr; byteCount: Integer); inline $AflFD; 

{ miscellaneous utility routines } 

function GetPixel (h,v: Integer): Boolean; inline $Aflt5; 

function Random: Integer; inline $AfiLl; 
procedure StuffHex (thingptr: Ptr; s:Str255); inline SAfltlj; 

procedure ForeColor (color: Longint); inline $AfltE; 

procedure BackColor (color: Longint); inline $Afib3; 

procedure ColorBit (whichBit: Integer); inline $Aflt^; 
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OSIntf 



The Macintosh operating system (Mac OS) is at the lowest level of Macintosh 
operations. It performs basic tasks such as input/output memory management 
and interrupt handling. Many of the Toolbox procedures and functions call Mac 
OS routines to support their operations. The OSIntf unit declares the Pascal 
interface to the Mac OS, naming the many constants, data types, variables, and 
routines. 

unit OSIntf (-fl); 
interface 

uses HenTypes, QuickDraw; 

const { for EventManager } 



everyEvent 


= -1 




NullEvent 


= D 




mouseDown 


= 1 




mouseup 


- E 




keyDown 


- 3 




keyUp 


= A 




autoKey 


= 5 




updateEvt 


- t 




diskEvt 


= 7 




activateEvt 


= fl 




networkEvt 


- la 




driverEvt 


= 11 




applEvt 


= 12 




appEEvt 


= 13 




app3E7t 


= lA 




app^Evt 


= 15 




{ event mask equates } 


mDovnHask 




E 


niUpMask 






keyDownMask 




fi 


keyUpMask 




It 


autoKeyMask 
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updateHask 




£.4 



app^ask - -3E7t,fl; 

{ to decipher event message for keyDown events > 
charCodeHask » $DODDDDFF; 
keyCodeHask = SQQQDFI'DD; 

{ modifiers } 

optionKey= ED^fl; { Bit 3 of high byte ) 

alphaLock* 102^; { Bit 2 } 

ShiftKey= 512; { Bit 1 } 

CmdKey= 25t.; { Bit Q } 

BtnState= 12fl; { Bit ? of low byte is mouse button state } 



diskHask 

activMask 



lEfl 
E5t 
IDE^ 
EQ^fl 

fiiqE 
lt3A< 



networkMask 
driverMask 



applMask 
appEHask 
app3Mask 
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activeFlag =1; { bit 0 of nodifiers for activate event > 



EvtHotEnb = 1; 



{ error for PostEvent > 



i for Memory Manager } 
" " -IDA; 

-IDR; 
-111; 
-HE; 
-117; 
0; 



HemFuUErr 
NilHandleErr = 
MemWZErr 
MeiPurErr 
HemLockedErr = 
NoErr 



{ file system error codes 



DirFulErr 
DskFulErr 
NSVErr 
lOErr 
BdNaiErr 
FNOpnErr 
EOFErr 
PosErr 
HFulErr 
TMFOErr 
FHFErr 

WPrErr 

FLckdErr 

VLckdBrr 

FBsyErr 

DupFNErr 

OpWrErr 

ParamErr 

RFNumErr 

GFPErr 

VolOffLinErr = 
PeriiiErr = 
VolOnLinErr * 
NSDrvErr 
KoMacDskErr - 
ExtFSErr 
FSRnErr 
BadMDBErr = 
HrPermErr 

lastDskErr * 

noDriveErr « 

offLinErr * 
noNybErr 

noAdrMkErr « 

dataVerErr = 

badCkSmErr = 

badBtSlpErr = 

noDtaMkErr = 
badDCkSum 

badDBtSlp = 

wrUnderEun = 

cantStepErr = 
tkDBadErr 

initlWMErr = 

twoSideErr = 
spdAdjErr 
seekErr 
sectNFErr 

firstDskErr * 

DirNFErr 



-33 

-3^ 
-35 
-3t 
-3? 
-3fi 
-39 
-<0 
-Al 

-A3 

-AA 
-AS 
-Ah 
-Al 
-4fl 

-5D 
-51 
-55 
-53 
-SA 
-55 
-5t 
-57 
-5fi 
-59 

-to 

-tl 

-ts 

-tt 
-t7 
-tfl 

-tq 

-7D 
-71 
-7E 
-73 
-lA 
-75 
-7fc 
-77 
-7fl 
-79 
-SO 
-fll 
-6A 



not enough room in heap zone } 

master pointer was NIL in HandleZone or other } 

HhichZone failed (applied to free block) } 

trying to purge a locked or non-purgeable block } 

block is locked > 

all is well > 



directory full } 
disk full } 
no such volume > 
I/O error > 
bad name } 
file not open ) 
end of file > 

tried to position to before start of file (r/w) } 
memory full (open) or file won't fit (load) } 
too many files open } 
file not found } 

diskette is write protected } 

file is locked } 

volume is locked } 

File is busy (delete) } 

duplicate filename (rename) } 

file already open with with write permission > 

error in user parameter list > 

refnum error } 

get file position error } 

volume not on line error (was Ejected) > 

permissions error (on file open) > 

drive volume already on-line at MountVol } 

no such drive (tried to mount a bad drive num) > 

not a Mac diskette (sig bytes are wrong) > 

volume in question belongs to an external fs > 

file system rename error > 

bad master directory block > 

write permissions error } 

last in a range of disk errors > 

drive not installed } 

r/w requested for an off-line drive > 

couldn't find 5 nybbles in EDO tries } 

couldn't find valid addr mark > 

read verify compare failed } 

addr mark checksum didn't check > 

bad addr mark bit slip nybbles } 

couldn't find a data mark header } 

bad data mark checksum > 

bad data mark bit slip nybbles } 

write underrun occurred } 

step handshake failed } 

track 0 detect doesn't change } 

unable to initialize IffM > 

tried to read End side on a 1-sided drive > 

unable to correctly adjust disk speed } 

track number wrong on address mark > 

sector number never found on a track > 

first in a range of disk errors } 



-lED; { directory not found > 
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TMWDOErr = -lEl; { no free WDCB available > 

BadMovErr = -1E5; { move into offspring error } 

HrgVolTypErr = -IBB; { wrong volume type error - operation not supported for MFS) 

FSDSIntErr » -127; { internal file system error > 



MaxSize 

fHasBundle 

finvisible 

fTrash 

fDesktop 

fDisk 



SflaOOQD; 

-3; 
-2; 
0; 



{ I/O constants > 
fsAtHark - D 
fsFroroStart = 1 
fsFroiLEOF = 2 
fsFromMark = 3 
rdVerify = t4 



fsCurPeriii 

fsRdPerm 

fsWrPerm 

fsRdWrPerm 

fsRdWrShPerm 



{ max data block size is A megabytes } 
i finder constants > 



{ ioPosHode values > 



{ ioPermission values > 



{ refNums from serial ports 
AinRefNum = -t; { 
AoutRefNum = -7; i 
BinRefNum « -fl; { 
BoutRefNum * -1; i 

{ baud rate constants } 
baud3D0 - 3flD; 
baudtOD = IfiR; 
baudlEDD = ^A; 
baudlfiOQ » bE; 
baud2^DD - 4b; 
baudBtOO = 3D; 
baud^fiDO = EE; 
baud7EDD = 1^; 
baudqbOD - 10; 
baudiqEQD = 4; 
baud57t.Da - D; 



> 

serial port A input } 
serial port ft output } 
serial port B input > 
serial port B output > 



{ sec channel configuration word } 
{ driver reset information masks > 
stoplO = IbBfl^; 
stoplS « -3E7t.fi; 
stopED = -lt.3fl4; 

noParity = D; 
oddParity = ^D^t; 
evenParity = lEEflfi; 



dataS = D; 

datat = 2Q4fl; 

data7 = 1D24; 

datafl « 3072; 



{ serial driver error masks } 
swOverrunErr = 1; 
parityErr = lb; 
hwOverrunErr = 32; 
framingErr « t^; 
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{ serial port configuratioa usage constants for Config field of SysParmType } 
useFree » D; 
useATalk » X; 
useflsync « 2; 

xOffWasSent = $60; { serial driver message constant > 

i for application parameter >. 

{ constants for message returned by the finder on launch } 
appOpen = 0; 
appPrint =1; 

SWmode = -1; 
FTmode = 1 ; 
FFmode = D; 

{ Desk Accessories 
accEvent 
accfiun 
accCursor 
accHena 
accOndo 
accCut 

accCopy = 
accPaste = 
accClear 

goodbye 

macXLMachine = D; 
macMachine « 1; 

{ if BitTst(ioDirFlg, .myParaffiBlk*.ioFlAttrib) then > 
ioDirFlg = 3; 

{ if BitAnd(ioDirMask, ioyParaiBlk*.ioFlAttrib) » ioDirMask then } 
ioDirMask = $1D; 

FSBtParlD 1; { DirlD of parent's root > 

FSRtDirlD " E; { Root DirlD } 

{ result codes for RelString > 

sortsBefore » -1; { strl < str? > 

sortsEqual » 0; { strl « str2 > 

sortsAfter « 1; { strl > strS > 

type 

EventRecord « record {for Event Manager > 

what : Integer; 

message : Longint; 

when : Longint; . 

where : Point; 
modifiers: Integer; 
end; 

Zone - record 



BkLim 


Ptr; 


PurgePtr 


Ptr; 


HFstFree 


Ptr; 


ZCBFree 


Longint; 


GZProc 


ProcPtr; 
Integer; 


MoreMast 


Flags 


Integer; 


CntRel 


Integer; 


MaxRel 


Integer; 


CntMRel 


Integer; 


HaxNRel 


Integer; 


CntEmpty 


Integer; 



{ for sound driver > 



- message definitions (in CSCode of Control Call) } 

t^; { event message from SysteiiEvent > 

ti5; { run message from Systemlask } 

y^; i cursor message from SystenTask > 

t7; { menu message from SystemHenu .} 

tfl; { undo message from SystemEdit > 

70; {cut message from SystemEdit } 

71; { copy message from SystemEdit } 

75; { paste message from SystemEdit > 

73; { clear message from SystemEdit > 

-1; { goodbye message } 

{ for "machine" parameter of Environs > 
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THz 

Size 

OSErr 



CntHandles 

MinCBFree 

PurgeProc 

SparePtr 

RllocPtr 

HeapData 

end; 

•Zone; 

Longint; 

Integer; 



Integer; 

Longint; 

ProcPtr; 

Ptr; 

Ptr; 

Integer; 



{ reserved for future } 



QEIenPtr = *QEleB; 



{ pointer to the start of a heap zone > 

{ size of a block in bytes > 

{ error code } 

i ptr to generic queue elenent } 



{ vertical blanking control block queue element > 
VBLTask « record 



qLink: QElemPtr; 
qType: Integer; 
vblAddr: ProcPtr; 
vblCount: Integer; 
vblPhase: Integer; 
end; 



{ link to next element } 

{ unique ID for validity check > 

{ address of service routine > 

{ count field for timeout > 

{ phase to allow synchronization } 
i VBLCntrlBlk > 

{ VBLQElPtr « *VBLTask; > 



evQEl = record 

qLink: QElemPtr; 
qType: Integer; 
evtQwhat: Integer; 
evtQmessage:LongInt; 
evtQwhen: Longint; 
evtQwhere: Point; 
evtQiodifiers: Integer; 
end; 



{ this part is identical to the EventRecord as. 
{ defined in Toollntf } 



DrvQEl = record 
qLink: 
qType: 
dQDrive: 
dQRefNum: 
dQFSID: 
dQDrvSize: 



QElemPtr; 

Integer; 

Integer; 

Integer; 

Integer; 

Integer; 



{ drive queue elements > 



end; 



{ ref num of the driver that handles this drive > 

{ id of file system that handles this drive } 

{ size of drive (51E-byte blocks); > 

{ not for drvs 1*2 > 



DrvQElPtr = *DrvQEl; 



TrapType - (OSTrap, ToolTrap); 



{ for NGet and NSet TrapAdress } 



{ file system } 

ParanBlkType * (IOParam,FileParam,VolumeParam,CntrlParam) ; 

OSType = packed array[l..<] of Char; { same as rsrc mgr's Restype } 

FInfo = record { record of finder info > 
fdType: OSType; { the type of the file } 
fdCreator: OSType; { file's creator } 

fdFlags: Integer; i flags/ e.g./ hasbundle; invisible, locked, etc. ) 
fdLocation: Point; { file's location in folder } 
fdFldr: Integer; { folder containing file > 

end; { FInfo } 



{ new BFS } 



FXInfo = 



record 

fdlconID: 



Integer; 



{ Icon ID } 



fdUnused: array[l..<] of Integer; f unused but reserved } 



fdComment: Integer; 
fdPutAway: Longint; 



{ comment ID > 
{ home dir ID } 
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end; 



DInfo * record 

frRect: Rect; 
frFlags: Integer; 
frLocation: Point; 
frView: Integer; 
end; 

DXInfo = record 

frScroll: Point; 
frOpenChain: LongInt; 
frUnused: Integer; 
f rCofliinent : Integer; 
frPutAway: LongInt; 
end; 



{ folder rect > 

{ flags > 

{ folder location } 

{ folder view } 



i scroll position } 

{ dir ID chain of open folders } 

{ unused but reserved } 

{ coninent > 

{ dir ID } 



ParamBlockKec record 

{ 12 byte header used by file and 10 system > 
gLink: QElemPtr; { queue link in header > 

qType: Integer; { type byte for safety check > 

ioTrap: Integer; { FS: the Trap } 

ioCiadaddr: Ptr; { FS: address to dispatch to > 

{ coimon header to all variants > 

ioCoflipletion: ProcPtr; { completion routine addr (D for synch calls) > 

ioResult: OSErr; { result code } 

ioNamePtr: StringPtr; { ptr to VoliFileName string } 

ioVRefNuro: Integer; { volume refnum (DrvNura for Eject and MountVol) } 

{different components for the different type of parameter blocks > 
case ParamBlkType of 



ioParam: 
(ioRefNura: Integer; 
ioVersNuKi: SignedByte; 
ioPermssn: SignedByte; 

ioBisc: Ptr; 



ioBuffer: Ptr; 
ioRegCount: LongInt; 
ioActCount: LongInt; 
ioPosMode: Integer; 
ioPosOf f set : LongInt ) ; 

FileParam: 

(ioFRefMum: Integer; 
ioFVersNum: SignedByte; 
fillerl: SignedByte; 
ioFDirlndex: Integer; 
ioFlAttrib: SignedByte; 
ioFlVersNum: SignedByte; 
ioFlFndrlnfo: FInfo; 
ioFlNum: LongInt; 
ioFlStBlk: Integer; 
ioFlLgLen: LongInt; 
ioFlPyLen: LongInt; 
ioFlRStBlk: Integer; 
ioFlRLgLen: LongInt; 
ioFlRPyLen: LongInt; 
ioFlCrDat: LongInt; 
ioFlMdDat: LongInt); 



{ refNura for I/O operation > 

{ version number } 

{ Open: permissions (byte) } 

{ Rename: new name > 

{ GetEOF/SetEOF: logical end of file > 

i Open: optional ptr to buffer > 

{ SetFileType: new type } 

{ data buffer Ptr } 

{ requested byte count; also = ioNewDirlD > 

{ actual byte count completed > 

{ initial file positioning > 

{ file position offset > 



( reference number > 

{ version number } 

{ GetFInfo directory index > 

{ GetFInfo: in-use bit-7, lock bit«D > 

.{ file version number > 

{ user info } 

{ GetFInfo: file number; TF- ioDirlD } 

{ start file block (D if none) > 

{ logical length (EOF) } 

{ physical length } 

{ start block rsrc fork > 

{ file logical length rsrc fork } 

{ file physical length rsrc fork > 

{ file creation date 4 time (32 bits in sees) } 

{ last modified date and time } 
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VolumeParam: 
(fillerE: Longint; 
ioVolIndex: Integer; 
ioVCrDate: Longint; 
ioVLsBkOp: Longint; 
ioVfttrb: Integer; 
ioVNmFls: Integer; 
ioVDirSt: Integer; 
ioVBlLn: Integer; 
ioVNmAlBlks: Integer; 
ioVAlBlkSiz: Longint; 
ioVClpSiz: Longint; 
ioAlBlSt: Integer; 
ioVNxtFNuin: Longint; 
ioVFrBlk: Integer); 



{ volune index number } 

{ creation date and time > 

{ last backup date and time > 

{ volume attrib } 

{ number of files in directory > 

{ start block of file directory } 

{ GetVolInfo: length of dir in blocks } 

{ GetVolInfo: nura blks (of alloc size) } 

{ GetVolInfo: alloc blk byte size > 

{ GetVolInfo: bytes to allocate at a time } 

{ starting disk(51E-byte) block in block map > 

{ GetVolInfo: next free file number } 

{ GetVolInfo: # free alloc blks for this vol } 



{ refNuffl for I/O operation } 
{ word for control status code > 
i operation-defined parameters } 
{ ParamBlockRec > 



CntrlParam: 

(ioCRefNum: Integer; 
CSCode: Integer; 

CSParam: array[D..lD3 of Integer); 
end; 

ParniBlkPtr = *ParamBlockEec; 

HParamBlockRec = record 

{ IE byte header used by the file system } 
qLink: QElemPtr; 
qType: Integer; 
ioTrap: Integer; 
ioCmdaddr: Ptr; 

{ common header to all variants > 
ioCompletion: ProcPtr; { completion routine, 
ioResult: OSErr; < result code } 

ioNamePtr: StringPtr; { ptr to pathname } 

ioVRefNum: Integer; { volume refnum } 

{ different components for the different type of parameter blocks } 
case ParamBlkType of 



or NIL if none } 



ioParam: 
(ioRefNum: Integer; 
ioVersNura: SignedByte; 
ioPermssn: SignedByte; 

ioMisc: Ptr; 

ioBuffer: Ptr; 
ioEeqCount: Longint; 
ioActCount: Longint; 
ioPosMode: Integer; 
ioPosOffset: Longint); 



{ refNum for I/O operation > 

{ version number > 

{ Open: permissions (byte) > 

{ HRename: new name > 

{ HOpen: optional ptr to buffer > 

{ data buffer Ptr } 

{ requested byte count } 

{ actual byte count completed > 

{ initial file positioning > 

{ file position offset > 



fileParam: 
(ioFRefNum: Integer; 
ioFVersNum: SignedByte; 
fillerl: SignedByte; 
ioFDirlndex: Integer; 
ioFlAttrib: SignedByte; 
ioFlVersNuin: SignedByte; 
ioFlFndrlnfo: FInfo; 
ioDirlD: Longint; 
ioFlStBlk: Integer; 
ioFlLgLen: Longint; 
ioFlPyLen: Longint; 
ioFlRStBlk: Integer; 



{ reference number } («choose either this or ioRefNum *) 

{ version number, normally D > 

{ HGetFlnfo directory index } 

{ HGetFlnfo: in-use bit=7, lock bit=D } 

{ file version number returned by GetFInfoz > 

{ user info } 

{ directory ID > 

{ start file block (D if none) > 

{ logical length (EOF) > 

{ physical length } 

{ start block rsrc fork > 
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ioFlRLgLen: Longint; 
ioFlRPyLen: Longint; 
ioFlCrDat: Longint; 
ioFlMdDat: Longint); 

volumeParam: 
(filler5: Longint; 

ioVolIndex: Integer; 

ioVCrDate: Longint; 

ioVLsMod: Longint; 

ioVAtrb: Integer; 

ioVNniFls: Integer; 

ioVBitMap: Integer; 

ioftllocPtr: Integer; 

ioVNmAlBlks: Integer; 

ioVAIBlkSiz: Longint; 

ioVClpSiz: Longint; 

ioRlBlSt: Integer; 

ioVNxtCNID: Longint; 

ioVFrBlk: Integer; 

ioVSigWord: Integer; 

ioVDrvInfo: Integer; 

ioVDRefNum: Integer; 

ioVFSID: Integer; 

ioVBkUp: Longint; 

ioVSegNum: Integer; 

ioVWrCnt: Longint; 

ioVFilCnt: Longint; 

ioVDirCnt: Longint; 

ioVFndrlnfo: array El. 
end; 



{ file logical length rsrc fork } 

{ file physical length rsrc fork } 

{ file creation date 4 time (32 bits in sees) } 

{ last modified date and time } 



{ volume index number > 

{ creation date and time > 

{ last date and time volume was flushed > 

{ volume attrib > 

{ number of files in directory > 

{ start block of volume bitmap > 

{ HGetVInfo: length of dir in blocks } 

{ HGetVInfo: num blks (of alloc size) > 

{ HGetVInfo: alloc blk byte size } 

{ HGetVInfo: bytes to allocate at a time > 

{ starting disk(512-byte) block in block map > 

{ HGetVInfo: next free file number } 

{ HGetVInfo: # free alloc blks for this vol } 

{ volume signature } 

{ drive number > 

{ driver refNum } 

{ ID of file system handling this volume } 
{ last backup date (0 if never backed up) > 
{ sequence number of this volume in volume set > 
{ volume write count > 
{ volume file count } 
{ volume directory count } 
.fil of Longint); { finder info, for volume } 
{ HParamBlockRec } 



HParraBlkPtr = *HParamBlockRec; 



FCBPBRec * record 

{ IE byte header used by 

qLink: QElemPtr; 

qType: Integer; 

ioTrap: Integer; 

ioCiiidftddr: Ptr; 

ioCompletion: ProcPtr; 

ioResult: OSErr; 

ioNamePtr: StringPtr; 

ioVRefNum: Integer; 

ioRefNum: Integer; 

filler: Integer; 

ioFCBIndx: Longint; 

ioFCBFlNm: Longint; 

ioFCBFlags: Integer; 

ioPCBStBlk: Integer; 

ioFCBEOF: Longint; 

ioFCBPLen: Longint; 

ioFCBCrPs: Longint; 

ioFCBVRefNum: Integer; 

ioFCBClpSiz: Longint; 

ioFCBParlD: Longint; 
end; 

FCBPBPtr = *FCBPBRec; 

CMovePBRec = record 
qLink: QElemPtr; 
qType: Integer; 
ioTrap: Integer; 
ioCndAddr: Ptr; 
ioCompletion: ProcPtr; 



{ for PBGetFCBInfo } 
the file and 10 system } 
{ queue link in header } 
{ type byte for safety check > 
{ FS: the Trap } 
{ FS: address to dispatch to > 
{ completion routine addr (D for synch calls) } 
{ result code > 

i ptr to Vol:FileName string > 

{ volume refnuffl (DrvNum for Eject and MountVol) > 

i file to get the FCB about } 

{ FCB index for .GetFCBInfo } 

{ file number > 

{ FCB flags > 

{ file start block > 

{ logical end-of-file } 

{ physical end-of-file > 

{ current file position } 

{ volume refNum } 

{ file clump size > 

{ parent directory ID } 



{ queue link in header } 

{ type byte for safety check } 

{ FS: the Trap } 

{ FS: address to dispatch to } 

i completion routine addr (0 for synch calls) } 
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ioResult: OSErr; 
ioNamePtr: StringPtr; 
ioVRefNum: Integer; 
fillerl: Longint; 
ioNewNarae: StringPtr; 
fillerE: Longint; 
ioNewDirlD: Longint; 
fillerB: array 
ioDirlD: Longint; 
end; 

CMovePBPtr = *CMovePBRec; 



{ result code } 

{ ptr to VoliFileName string > 

{ volume refnum (DrvNum for Eject and MountVol) } 

{ name of new directory } 

{ directory ID of new directory > 
of Longint; 

{ directory ID of current directory } 



WDPBRec = record 

qLink: QEleinPtr; 

qType: Integer; 

ioTrap: Integer; 

ioCmdAddr: Ptr; 

ioCompletion: ProcPtr; 

ioResult: OSErr; 

ioNamePtr: StringPtr; 

ioVRefNum: Integer; 

fillerl: Integer; 

ioWDIndex: Integer; 

ioWDProcID: Longint; 

ioHDVRefNum: Integer; 

fillerE: array [I..?] of 

ioWDDirlD: Longint; 
end; 

HDPBPtr = "WDPBRec; 



{ for PBGetWDInfo > 

{ queue link in header } 

{ type byte for safety check > 

{ FS: the Trap > 

{ FS: address to dispatch to > 

{ completion routine addr (D for synch calls) > 

i result code > 

{ ptr to Vol:FileName string > 

{ volume refnum } 

{ not used } 

{ working directory index for GetWDInfo } 

{ WD's ProcID } 

{ HD's Volume RefNum > 
Integer; 

{ WD's DirlD > 



CInfoType = (inputParam, hFilelnfOi dirlnfo); 

CInfoPBRec = record { ioDirFlg clear; equates for catalog information return } 



qLink: QElemPtr; 
qType: Integer; 
ioTrap: Integer; 
ioCrodAddr: Ptr; 
ioCompletion: ProcPtr; 
ioResult: OSErr; 
ioNamePtr: StringPtr; 
ioVRefNum: Integer; 
ioFRefNum: Integer; 
fillerl: Integer; 
ioFDirlndex: Integer; 
ioFlAttrib: SignedByte; 
fillerE: SignedByte; 
case CInfoType of 
inputParam: 
(filler3: array[l..fi] of Integer; 
ioDirlD: Longint); 
hFilelnfo: 
(ioFlFndrlnfo: FInfo; 
ioFlNum: Longint; 
ioFlStBlk: Integer; 
ioFlLgLen: Longint; 
ioFlPyLen: Longint; 

Integer; 
Longint; 
Longint; 



{ queue link in header } 

{ type byte for safety check > 

i FS: the Trap > 

{ FS: address to dispatch to } 

{ completion routine addr (0 for synch calls) } 

{ result code } 

i ptr to Vol:FileName string } 

{ volume refnum (DrvNum for Eject and MountVol) > 

{ file reference number > 

{ GetFInfo directory index > 

{ GetFInfo: in-use bit=?, lock bit=a } 



ioFlRStBlk: 
ioFlRLgLen: 
ioFlRPyLen: 
ioFlCrDat: Longint; 
ioFlMdDat: Longint; 
ioFlBkDat: Longint; 
ioFlXFndrlnfo: FXInfo; 
ioFlParlD: Longint; 
ioFlClpSiz: Longint); 



{ user info > 

{ GetFInfo: file number > 

{ start file block (D if none) } 

{ logical length (EOF) } 

{ physical length > 

{ start block rsrc fork > 

{ file logical length rsrc fork } 

{ file physical length rsrc fork } 

{ file creation date & time (32 bits in sees) > 

{ last modified date and time > 

{ file last backup date > 

{ file additional finder info bytes > 

{ file parent directory ID (integer?) } 

{ file clump size > 
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dirlnfo: { equates for directory information return } 

(ioDrUsrWds: DInfo; < directory's user info bytes > 

ioDrDirlD: Longint; { directory ID > 

ioDrNniFls: Integer; { number of files in a directory } 

filler^: array of Integer; 

ioDrCrDat: Longint; { directory creation date > 

ioDrMdDat: Longint; { directory modification date > 

ioDrBkDat: Longint; { directory backup date } 

ioDrFndrlnfo: DXInfo; { directory finder info bytes > 

ioDrParlD: Longint); < directory's parent directory ID > 



CInfoPBPtr = '^ClnfoPBfiec; 



{ 20 bytes of system parameter area } 



SysParmType = packed record 
Valid: Byte; 
ftTalkA: Byte; 
RTalkB: Byte; 
Config: Byte; 
PortA: Integer; 
PortB: Integer; 
Alarm: Longint; 
Font: Integer; 
KbdPrint: Integer; 



VolClik: Integer; 



Misc: Integer; 



end; 

SysPPtr = "SysParmType; 



{ validation field ($A?) } 

{ AppleTalk node number hint for port A } 

{ AppleTalk node number hint for port B > 

{ ATalk port configuration A = bits 4-7, B * D-3 } 

{ sec port A configuration > 

{ sec port B configuration } 

{ alarm time } 

{ default font ID > 

{ high byte = kbd repeat } 

i high nibble = thresh in ^/fcOths } 

{ low nibble = rates in 2/E,Dths > 

{ low byte = print stuff } 

{ low 3 bits of high byte = volume control } 
high nibble of low byte = double time in </tDths > 

low nibble of low byte = caret blink time in ^/tOths } 

{ EEEC EEEE PSKB FFHH > 

{ E = extra } 

{ P - paranoia level } 

{ S - mouse scaling > 

{ K « key click } 

{ B ^ boot disk } 

{ F = menu flash > 

{ H « help level > 
{ SysParmType } 



{ volume control 

VCB = record 
qLink: 
qType: 
vcbFlags: 
vcbSigWord: 
vcbCrDate: 
vcbLsMod: 
vcbAtrb: 
vcbNmFls: 
vcbVBMSt: 
vcbAllocPtr: 
vcbNmAlBlks: 
vcbAlBlkSiz: 
vcbeipSIz: 
vcbAlBlSt: 
vcbNxtCNID: 
vcbFreeBks : 
vcbVN: 
vcbDrvNum: 
vcbDRefNum: 
vcbFSID: 
vcbVRefNum: 



block data structure > 



QElemPtr; 

Integer; 

Integer; 

Integer; 

Longint; 

Longint; 

Integer; 

Integer; 

Integer; 

Integer; 

Integer; 

Longint; 

Longint; 

Integer; 

Longint; 

Integer; 

STRIN6[E7]; 

Integer; 

Integer; 

Integer; 

Integer; 



{ link to next element > 
{ not used > 
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end; 



vcbMAdr: 

vcbBufAdr: 

vcbMLen: 

vcbDirlndex: 

vcbDirBlk: 

vcbVolBkup: 

vcbVSegNum: 

vcbWrCnt: 

vcbXTClpSiz: 

vcbCTClpSiz: 

vcbNmRtDirs: 

vcbFilCnt: 

vcbDirCnt: 

vcbFndrlnfo: 

vcbVCSize: 

vcbVBMCSiz: 

vcbCtlCSiz: 

vcbXTAlBlks: 

vcbCTAlBlks: 

vcbXTRef: 

vcbCTRef: 

vcbCtlBuf; 

vcbDirlDM: 

vcbOf f sM : 



Ptr; 
Ptr; 

Integer; 
Integer; 
Integer; 

Longint; 

Integer; 

Longint; 

Longint; 

Longint; 

Integer; 

Longint; 

Longint; 

Flnfo; 

Integer; 

Integer; 

Integer; 

Integer; 
Integer; 
Integer; 
Integer; 
Longint; 
Longint; 
Integer; 



< new HFS extensions } 



{ additional VCB info } 



i general queue data structure ) 
QHdr = record 

QFlags: Integer; i misc flags > 

QHead: QElemPtr; { first elein, } 

QTail: QElemPtr; { last elem } 
end; i QHdr } 

QHdrPtr = *QHdr; 

{ there are currently four types of queues: } 

{ VType, queue of Vertical Blanking Control Blocks > 

{ lOQType, queue of I/D queue elements > 

i DrvType, queue of drivers } 

{ EvTyper queue of Event Records > 

{ FSQType, queue of VCB elements } 

{ TimerType no longer is used. > 

{ DrvType replaces it here in enum type } 

QTypes = { dummyType t vType , ioQType , drvQType , e vType , f sQType ) ; 



QElem » record 

case QTypes of 
vType: 
(vblQelem: VBLTask); 



{ vertical blanking > 



ioQType: 

(ioQElem: ParamBlockRec) ; { I/O parameter block } 



drvQType: 
(drvQElem: DrvQEl); 

evType: 
(evQElem: EvQEl); 

fsQType: 
(vcbQElem: VCB); 



{ drive } 



{ event } 



end; 



DCtlEntry record 

DCtlDriver: Ptr; 



{ volume control block > 

{ QElem > 

{ device control entry > 
{ ptr to ROM or handle to RRM driver } 
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DCtlFlags: Integer; 
DCtlQHdr: QHdr; 
DCtlPosition: Longint 
DCtlStorage: Handle; 
DCtlRefNum: Integer; 
DCtlCurTicks: Longint 
DCtlWindow: Ptr; 
DCtlDelay: Integer; 
DCtlEMask: Integer; 
DCtlHenu: Integer; 
end; 

DCtlPtr - *DCtlEntry; 
DCtlHandle = *DCtlPtr; 



{ flags } 

{ driver's I/O queue } 
; { byte pos used by read and write calls > 

{ hndl to RAM drivers private storage } 

{ driver's reference number > 
;{ long counter for timing system task calls } 

{ ptr to driver's window if any } 

{ number of ticks btwn sysTask calls } 

{ desk acessory event mask > 

{ menu ID of menu associated with driver > 
{ DCtlEntry } 



{ for Serial Driver } 
SerShk » packed record 

fXOn: Byte; 

fCTS: Byte; 

xon: Char; 

xoff: Char; 

errs: Byte; 

evts: Byte; 

fInX: Byte; 

null: Byte; 
end; 



handshake control fields > 

{ XON flow control enabled flag > 

{ CTS flow control enabled flag > 

{ XOn character > 

{ XOff character } 

< errors mask bits } 

{ event enable mask bits > 

{ input flow control enabled flag > 

{ unused } 



{ parameter block structure for fil> 
SerStaRec - packed record 

cumErrs: Byte; 
XOFFSent: Byte; 
rdPend: Byte; 
wrPend: Byte; 
ctsHold: Byte; 
XOFFHold: Byte; 
end; 

{ for sound driver } 

{ for ^-tone sound generation } 

Wave = packed array [D. .2551 of Byte; 

ffavePtr = *Have; 

FTSoundRec = record 

duration: Integer; 

soundlRate: Longint; 

soundlPhase: Longint; 

soundERate: Longint; 

soundEPhase: Longint; 

sound3Rate: Longint; 

sound3Phase: Longint; 

soundlRate: Longint; 

soundlPhase: Longint; 

soundlWave: WavePtr; 

soundEWave: ffavePtr; 

sound3Wave: WavePtr; 

sound-wave: WavePtr; 
end; 

FTSndRecPtr = *FTSoundRec; 

FTSynthRec = record 

mode: Integer; 
sndRec: FTSndRecPtr; 
end; 

FTSynthPtr = "FTSynthRec; 

Tone = record 

count: Integer; 
amplitude: Integer; 



and 10 routines > 

{ cumulative errors report } 

{ XOff Sent flag > 

{ read pending flag > 

{ write pending flag > 

{ CTS flow control hold flag > 

{ XOff flow control hold flag } 
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duration: Integer; 
end; 



Tones = array[D. .SDDQ] of Tone; 



SHSynthRec - record 

node: Integer; 
triplets: Tones; 
end; 

StfSynthPtr ^ *SffSynthRec; 

freeffave - packed array [ 0. .3QDDD1 of Byte; 



FFSynthRec 



record 

mode: Integer; 
count: Fixed; 
waveBytes: freeHave; 
end 



FFSynthPtr » "FFSynthRec; 



DateTimeRec 



record i 
Year, 
Month, 
Day, 
Hour, 
Minute, 
Second, 

DayOfHeek: Integer; 
end; { 



for date and time 
{ 1^0^,1^05,... } 



1,. 

D,. 
0,. 
1/. 



12 corresponding to Jan,..., Dec } 
.31 } 
.,E3 > 
.,5R } 
.,5q } 

? corresponding to Sun,,.., Sat } 



DateTiroeRec } 



appFile « record { for application parameter } 

vRefNum: Integer; 
ftype: OSType; 

versNum: Integer; { versNura in high byte > 
fNanie: str255; 
end; {appFile> 



SPortSel = (SPortR,SPortB); 

DriveKind = (sony, hardSO); 

DrvSts * record 
track: 
writeProt: 
disklnPlace: 
installed: 
sides : 
DriveQLink: 
DriveQVers: 
dqDrive: 
dqRefNum: 
dqFSID: 

case DriveKind of 



{ for RAM serial driver > 
{ for disk driver > 



Integer; 

SignedByte; 

SignedByte; 

SignedByte; 

SignedByte; 

QElemPtr; 

Integer; 

Integer; 

Integer; 

Integer; 



sony: 

(twoSideFrot: SignedByte; 



needsFlush: 
diskErrs: 
hardaO: 
(DriveSize: 
DriveSl: 
DriveType: 
DriveManf : 



SignedByte; 
Integer) ; 

Integer; 
Integer; 
Integer; 
Integer; 



{ current track } 

{ bit 7 = 1 if volume is locked } 

{ disk in drive } 

{ drive installed > 

{ -1 for E-sided, D for 1-sided } 

{ next queue entry } 

{ 1 for HDED } 

{ drive number > 

{ driver reference number > 

{ file system ID > 



{ -1 for E-sided, D for 1-sided; > 

{ valid after first read or write } 

{ -1 for Mac Plus drive } 

{ soft error count > 

{ drive block size low word > 

{ drive block size high word } 

{ 1 for HD20 > 

{ 1 for Rpple Computer, Inc. > 
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DriveChar: Byte; { E3D ($Et) for HD5D } 

DriveMisc: SignedByte) { 0 - reserved } 

end; 

{ for Event Manager } 

functioa PostEvent(eventNuiii: Integer; eventMsg: Longint): OSErr; external; 
function PPostEvent(eventCode: Integer; eventMsg: Longint; 

var qEl: EvQEl): OSErr; external; 
procedure FlushEvents(whichMask,stopMask: Integer); inline $BD1F/ $AD35; 
procedure SetEventMask(theMask: Integer); inline $31DF, $UW; 
function OSEventAvail(mask: Integer; var theEvent: EventBecord) : Boolean; external; 
function GetOSE vent (mask: Integer; var theEvent: EventBecord): Boolean; extended; 

{ OS utilities > 

function HandTofland(var theHndl: Handle): OSErr.; external; 

function PtrToXHand(srcPtr: Ptr; dstHndl: Handle; size: Longint): OSErr; external;. 

function PtrToHand(srcPtr: Ptr; var dstHndl: Handle; size: Longint): OSErr; external; 

function HandfindHand{handl,handE: Handle): OSErr; external; 

function PtrAndHand(ptrl: Ptr; handE: Handle; size: Longint): OSErr; external; 

procedure SysBeep(duration: Integer); inline $ARCfl; 

procedure Environs(var roni/ machine: Integer); external; 

procedure Restart; external; 



{ routines to set A5 to CurrentAB and then restore AS to previous value } 
{ useful for ensuring good world for lOCoiiipletion routines } 
procedure SetUpAB; inline $5FDD, $EA7flr $D^04; 

{ MOVE.L A5,--(SP) ;save old A5 on stack 

MOVE.L Current AS, A5 ;get the real AS > 
procedure BestoreAS; inline $dA5F; 

{ MOVE.L (A?)+,A5 ;restore AS > 

{ from HEAPZONE.TEXT > 

procedure SetApplBase{startPtr: Ptr); external; 

procedure InitApplZone; external; 

procedure InitZone(pgrowZone: ProcPtr; 

cmoreMasters: Integer; 

lifflitPtr,startPtr : Ptr); external; 
function GetZone: THz; external; 
procedure SetZone{hz: THz); external; 

function ApplicZone: THz; inline $EEBfl, $DEAA; 
function SystemZone: THz; inline $EEBfi, $DEAt; 

function CompactMeffl(cbNeeded: size): size; external; 

Procedure PurgeHem(cbNeeded: size); external; 
unction FreeMem: Longint; external; 
procedure ResrvMem(cbNeeded: size); external; 
function MaxMem(Var grow: size): size; external; 
function TopMem: Ptr; inline $EEBfl, $DlDfl; 

procedure SetGrowZone(growZone: ProcPtr); external; 
procedure SetApplLimit(zoneLiniit: Ptr); external; 
function GetApplLimit: Ptr; inline $EEBfl, $0130; 
function StackSpace: Longint; external; 

rocedure PurgeSpace (var total, contig: Longint); external; 
unction MaxBlock: Longint; external; 

procedure MaxApplZone; external; 
procedure MoveHHi (h: handle); external; 

function NewPtr(byteCount: size): Ptr; external; 

? rocedure DisposPtr(p: Ptr); external; 
unction GetPtrSize(p: Ptr): size; external; 
procedure SetPtrSize(p: Ptr; newSize: size); external; 
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function PtrZone(p: Ptr): THz; external; 

function NewHandle(byteCount: size): handle; external; 

function NewEoptyHandle: handle; external; 

rocedure DlsposHandle(h: handle); external; 

unction GetflandleSize(h: handle): size; external; 
procedure SetHandleSize(h: handle; newSize: size); external; 
function HandleZone(h: handle): THz; external; 
function RecoverHandle(p: Ptr): handle; external; 
procedure EniptyHandle{h: handle); external; 
procedure ReAllocHandle{h: handle; byteCount: size); external; 

procedure HLock(h: handle); external; 
procedure HUnLoclc(h: handle); external; 
procedure HPur9e(h: handle); external; 
procedure HNoPurge(h: handle); external; 

procedure HSetRBit(h: handle); external; 

procedure HClrRBit(h: handle); external; 

procedure HSetState(h: handle; flags: SignedByte); external; 

function HGetState(h: handle): SignedByte; external; 

procedure HoreHasters; external; 

Procedure BlockHove(srcPtr, destPtr: Ptr; byteCount: size); external; 
unction HenError: OSErr; inline $3E6fir $DEBQ; 

function GZSaveHnd: handle; inline $5EBfi/ $Q3Efl; 



{ interface for core routines pertaining to the vertical retrace mgr } 
i routines defined in VBLCORE.TEXT > 
function VInstall(VBLTaskPtr: QElemPtr): OSErr; external; 
function VReniove(VBLTaskPtr: QElemPtr): OSErr; external; 

{ interface for operating system dispatcher > 
{ routines defined in DISPATCH. TEXT > 

function GetTrapAddress(trapNum: Integer): Longint; external; 
procedure SetTrapAddress(trapAddr: Longint; trapNum: Integer); external; 
function NGetTrapflddress(trapNum: Integer; tTyp: TrapType): Longint; external; 
procedure NSetTrapAddress(trapAddr: Longint; trapNum: Integer; tTyp: TrapType); external; 



{ interface for utility core routines (defined in sysutil) > 

function GetSysPPtr: SysPPtr; external; 

function WriteParam: OSErr; external; 

function SetDateTime(time: Longint) : OSErr; external; 

function BeadDateTinie(var tiie: Longint) :OSErr; external; 

procedure GetDateTinte(7ar sees: Longint); external; 

procedure SetTiine(d: DateTimeRec) ; external; 

procedure GetTimejvar d: DateTimeRec); external; 

procedure DateESecs(d: DateTimeRec; var s: Longint); external; 

procedure SecsEDate(s: Longint; var d: DateTimeRec); external; 

procedure Delay (numTicks: Longint; var finalTicks: Longint); external; 

function Equals tring(strl,strS: StrE55; caseSens,diacSens: Boolean) : Boolean; external; 



function BelString(aStr,bStr: Str555; caseSenS/ diacSens: Boolean): Integer; external; 



procedure OprString(var theString: StrE55; diacSens: Boolean); external; 
function InitUtil: OSErr; inline $AD3F, $3EflD; 

procedure OnLoadSeg(routineAddr: Ptr); inline $RRF1; 
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procedure ExitToShell; inline 

procedure 6etAppParnis(Tar apName: str555; var apRefNum: Integer; 

var apParam: Handle); inline $ARF5; 
procedure CountflppFiles{var message: Integer; var count: Integer); external; 
procedure GetAppFiles( index: Integer; var theFile: AppFile); external; 
procedure ClrAppFiles( index: Integer); external; 

{ queue routines - part of Macintosh core utility routines > 
procedure FInitQueue; inline $Aait,; 

procedure Enqueue (qElement: QElemPtr; qHeader: QfldrPtr); external; 

function Dequeue (qElement: QEIeinPtr; qHeader: QHdrPtr): OSErr; external; 

function GetFSQHdr: QHdrPtr; external; 

function GetDrvQHdr: QHdrPtr; external; 

function GetVCBQHdr: QHdrPtr; external; 

function GetVBLQHdr: QHdrPtr; external; 

function GetEvQHdr: QHdrPtr; external; 

function GetDCtlEntry(refNum: Integer): DCtlHandle; external; 

function PBOpen(paraiiiBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBClose(paramBiock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBRead(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBHrite(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBControl(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBStatus(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBKillIG(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBGetVInfo(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBGetVol(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBSetVol{paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBFlushVol(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBCreate(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBDelete(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBOpenRF(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBRename(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBGetFInfo(pararaBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBSetFInfo(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBSetFLock(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBRstFLock(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBSetFVers(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBAllocate(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBGetEOF(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBSetEOF(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBGetFPos(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBSetFPos(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBFlushFile(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBMountVol(paramBlock: ParmBlkPtr): OSErr; external; 

function PBlInMountVol(paramBlock: ParmBlkPtr): OSErr; external; 

function PBEject(paraiBlock: ParmBlkPtr): OSErr; external; 

function PBOffLine(paramBlock: ParmBlkPtr): OSErr; external; 

procedure AddDrive(drvrRefNuin: Integer; drvNum: Integer; QEl: drvQElPtr); external; 

function PBOpentfD(paramBlock: WDPBPtr; aSync: Boolean): OSErr; external; 

function PBCloseWD(pararaBlock: WDPBPtr; aSync: Boolean): OSErr; external; 

function PBHSetVol(paramBlock: ffDPBPtr; aSync: Boolean): OSErr; external; 

function PBHGetVol(paramBlock: ffDPBPtr; aSync: Boolean): OSErr; external;- 

function PBCatMoveiparamBlock: CMovePBPtr; aSync: Boolean): OSErr; external; 

function PBDirCreate{paramBlock: hParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBGetHDInfofparamBlock: ffDPBPtr; aSync: Boolean): OSErr; external;- 

function PBGetFCBInfo(paramBlock: FCBPBPtr; aSync: Boolean): OSErr; external; 

function PBGetCatInfo(paraniBlock: CInfoPBPtr; aSync: Boolean): OSErr; external; 

function PBSetCatlnfojparaniBlock: CInfoPBPtr; aSync: Boolean): OSErr; external; 

function PBAllocContig(parainBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBLockRange(paramBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBOnLockRange(parainBlock: ParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBSetVInfo(paramBlock: hParmBlkPtr; aSync: Boolean): OSErr; external; 



396 



Turbo Pascal for the Macintosh 



function PBHGetVInfo(paraiiiBLock: hParniBlkPtr; aSync: Boolean): OSErr; external; 

function PBHOpen(parainBlock: hParniBlkPtr; aSync: Boolean): OSErr; external; 

function PBHOpenRF(pararaBlock: hParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBHCreate{paraniBlock: hParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBHDelete(paraniBlock: hParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBHRenameiparaiBlock: hParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBHRstFLock(paranBlock: hParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBHSetFLock(paramBlock: hParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBHGetFInfo(paramBlock: hParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBHSetFInfo(paraiiiBlock: hParmBlkPtr; aSync: Boolean): OSErr; external; 

function PBSetPEOF(paraiiiBlock: hParmBlkPtr; aSync: Boolean): OSErr; external; 

function FSOpen(fileName: StraSE; vRefNuro: Integer; 

var refNum: Integer): OSErr; external; 
function FSClose( refNum: Integer): OSErr; external; 
function FSRead( refNum: Integer; 

var count: Longint; buffPtr: Ptr): OSErr; external; 
function FSKrite( refNum: Integer; 

var count: Longint; buffPtr: Ptr): OSErr; external; 
function Control (refNum: Integer; csCode: Integer; 

csPararaPtr: Ptr): OSErr; external; 
function Status (refNum: Integer; csCode: Integer; 

csParamPtr: Ptr): OSErr; external; 
function KillIO( refNum: Integer): OSErr; external; 

{ volume level calls } 

function GetVInfo(drvNum: Integer; volName: StringPtr; var vRefNum: Integer; 

var FreeBytes: Longint): OSErr; external; 
function GetFInfo(fileName: Str555; vRefNum: Integer; 

var Fndrlnfo: FInfo) :OSErr; external; 
function GetVol(volName: StringPtr; var vRefNum: Integer) :OSErr; external; 
function SetVol(volName: StringPtr; vRefNum: Integer): OSErr; external; 
function UnMountVol(volName: StringPtr; vRefNum: Integer) :OSErr; external; 
function Eject (volNaie: StringPtr; vRefNum: Integer): OSErr; external; 
function FlushVol(volName: StringPtr; vRefNum: Integer) : OSErr; external; 

{ file level calls for unopened files } 

function Create (fileName: Str255; vRefNum: Integer; creator: OSType; 

fileType: OSType) :OSErr; external; 
function FSDelete( fileName: Stress; vRefNum: Integer) :OSErr; external; 
function OpenRF( fileName: StrasS; vRefNum: Integer; 

var refNum: Integer): OSErr; external; 
function Rename (oldName: Str255; vRefNum: Integer; 

newName: Str255) : OSErr; external; 
function SetFInfo( fileName: Str^SS; vRefNum: Integer; 

Fndrlnfo: FInfo) :OSErr; external; 
function SetFLock( fileName: StrESS; vRefNum: Integer) :OSErr; external; 
function RstFLock( fileName: StrSSS; vRefNui: Integer) :OSErr; external; 

{ file level calls for opened files > 

function allocate (refNum: Integer; var count: Longint) :OSErr; external; 
function GetEOF( refNum: Integer; var LogEOF: Longint) :OSErr; external; 
function SetEOF( refNum: Integer; LogEOF: Longint) :OSErr; external; 
function GetFPos( refNum: Integer; var filePos: Longint) :OSErr; external; 
function SetFPos( refNum: Integer; posMode: Integer; posOff: Longint): OSErr; 
external; 

function 6etVRefNum(fileRefNum: Integer; var vRefNum: Integer): OSErr; external; 
< serial driver interface > 

function OpenDriver(name: StrESS; var drvrRefNum: Integer): OSErr; external 
function CloseDriver( refNum: Integer) :OSErr; external 

function SerReset( refNum: Integer; serConfig: Integer): OSErr; external; 
function SerSetBuf (refNum: integer; serBPtr: Ptr; serBLen: Integer): 
OSErr; external; 

function SerHShake( refNum: Integer; flags: SerShk): OSErr; external; 
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function SerSetBrk(refNuni: Integer): OSErr; external; 
function SerClrBrk(refNuin: Integer): OSErr; external; 
function SerGetBuf (refNui: Integer; 

var count: longint): OSErr; external; 
function SerStatus(refNun: Integer; 

Tar serSta: SerStaRec): OSErr; external; 
function DiskEject(drTnuiii: Integer): OSErr; external; 
function SetTagBuffer(buffPtr: Ptr): OSErr; external; 
function DriveStatus(drvNuiR: Integer; var status: DrvSts): OSErr; external; 
function RaBiSDOpen(whichPort: SPortSel): OSErr; external; 
procedure RaiiiSDClose(whichPort: SPortSel); external; 

{ for sound driver > 

procedure SetSoandVol( level: Integer); external; 
procedure GetSoundVol{var level: Integer); external; 

procedure StartSound(synthRec: Ptr; numBytes: Longint; CoapletionRtn: ProcPtr); external; 

Procedure StopSound; external; 
unction SoundDone: Boolean; external; 

{ for the system error handler } 

procedure SysError(errorCode: Integer); inline $301Fi $ARCR; 
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Tocillntf 



Toollntf implements the Macintosh's user interface features: windows, menus, 
controls, dialog boxes, text editing commands, and so on. This unit is needed in 
any Mac-style program. 

unit Toollntf ( -R); 

interface 

nses HenTypes, QuickDraw /Oslntf; 
const i for FontManager > 



conmaadHark 


= $11; 


checKHark 


= $ia; 


aianondnark 


= $13; 


appleHark 


= $14; 


systemFont = 


D 




applFont 


1 




newYork 


E 




geneva 


3 




nonaco = 


A 




Venice 


5 




london 


t 




athens 


7 




sanFran 


fi 




toronto 






Cairo 


11 




los&ngeles - 


IE 




tines 


50 




helvetica = 


El 




courier 


EE 




symbol = 


E3 




Dobile = 


S4 




propFont 


$HOaD; 


prpFntH 


IRDQl; 


prpFnttf 


$qDDE; 


prpFntHtf 


$qOD3; 


fixedFont = 


$BODD; 


fxdFntH 


$B0D1; 


fxdFnttf 


$BDDE; 


fxdFntHW = 


$BDD3; 


fontWid 


SACBQ; 


{ for Window Manager > 


wDraw 




0; 


wHit 


s 


1; 


wCalcRgns 




E; 


wNew 




3; 


wDispose 




4; 


wGrow 




5; 


wDrawGIcon 






dialogKind 


= 2 




userKind 


= a 




deskPatID ^ 


IE,; 





{ window messages > 



{ types of windows > 

{ desk pattern resource ID } 
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documentProc 

dBoxProc 

plainDBox 

altDBoxProc 

noGrowDocProc 

zooniDocProc 

zoomNoGrow 

rDocProc 

inDesk 

inMenuBar 

inSysWindow * 

inContent 

inDrag 

inGrow 

inGoAvay 

inZooroln 
inZooinOut 

wNoHit 
vInContent 
wInDrag 
vInGrov 
vlnGoAvay 



= D; 

- 1; 

' 3; 

• 

* a; 

- 12; 

- It; 

D; 
1; 
2; 
3; 
^; 
5; 
t; 



{ window definition procedure IDs } 



f FindHindow result codes > 



7; 

- fl; 

= 0; 

« 1; 

- a; 

= 3; 



wlnZoomln = 5; 
wlnZooniOut ^ t>; 

noConstraint D; 
hAxisOnly * 1; 
vAxisOnly * E; 

teJustLeft = D; 
teJustRight = -1; 
teJustCenter « 1 ; 

{ for Resource Manager > 
{ resource attribute byte) 



{ new lEAK ROH > 

{ defProc hit test codes } 

{ new IdAK ROH } 

{ axis constraints for DragGrayRgn call > 



{ for TextEdit } 



resSysHeap 
resPurgeable 
resLocked 
resProtected 
resPreload 
resChanged . 

napReadOnly 

mapCompact 

mapChanged 

resNotFound 
resFNotFound 
addResFailed 
rivResFailed 



lEfl; 
t<; 
3E; 

-ISE; 

-iq<; 

-IRt; 



{ system or application heap? > 

{ purgeable resource? > 

{ load it in locked? > 

{ protected? } 

{ load in on OpenResFile? > 

{ resource changed? > 

{ resource file read-only > 

{ compact resource file > 

{ write map out at update > 

{ resource not found > 

< resource file not found > 

{ AddResource failed } 

{ RmveResource failed > 



{ ID'S for resources provided in sysResDef } 

{ standard cursor definitions } 
iBeamCursor * 1; { text selection cursor } 

crossCursor = E; {for drawing graphics } 

plusCursor =3; { for structured selection } 

watchCursor * 4; { for indicating a long delay } 



stoplcon 
notelcon 



0; 
1; 



{ icons } 
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cautionlcon « 2; 



{ patterns } 
sysPatListID 



D; 



{ ID of PAT# which contains 3fl patterns } 



{ for Control Manager > 
dravCntl "0; { control messages > 



testCntl 
calcCRgns 
initCntl 
dispCntl 
posCntl 
thumbCntl 
dragCntl 
autoTrack 



inButton 

inCheckbox 

inUpButton 

inDownButton 

inPageUp 

InPageDown 

inThunib 



ID; 
U; 
20; 

23; 
lE^; 



pushButProc = D 
checkBoxProc * 1 
radioButProc « E 
scrollBarProc - Xt 



useWFont 



6; 



{ FindControl result codes } 



{ control definition proc ID'S > 



Qserltem = 


D; 




{ 


ctrllten « 


<; 






btnCtrl = 


0; 




i 


chkCtrl - 


1; 






radCtrl = 


E; 






resCtrl = 


3; 






statText 


s 


fl; 


{ 


editText 


s 


It; 


{ 


iconlten 




32; 


{ 


piclten 


s 


W; 


{ 


itenDisable 




lEfi; 


{ 



ok 

cancel 



1; 

E; 



{ for Menu Manager } 
noMark. » D; 
TextMenuProc = 0; 



{ OK button is first by convention > 

{ cancel button is second by convention > 



{ nark symbol for Harklteni } 



{ menu defProc messages } 
mDrawMsg = D; 
mChooseMsg = 1; 
mSizeMsg = E; 



{ for Scrap Manager > 
noScrapEirr « -IDD; 
noTypeErr ■ -lOE; 

{ package manager } 
dsklnit - S; 
stdFile = 3; 
flPoint - A; 
trFunc - 5; 



{ desk scrap isn't initialized } 



{ disk initializaton } 

{ standard file > 

{ floating-point arithmetic > 

{ transcendental functions > 
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intOtil = fc; 
bdConv = 7; 



{ international utilities > 
{ binary/decimal conversion } 



type 



Intt.4Bit » 
record 

hiLong: Longint; 

loLong: Longint; 
end; 

CursPtr = *Cursor; 
CursHandle = *CursPtr; 

PatPtr = *Pattern; 
PatHandle = *PatPtr; 



FMInput * packed record 

family: Integer; 
size: Integer; 
face: Style; 
needBits: Boolean; 
device: Integer; 
numer: Point; 
denom: Point; 
end; 



{ general utilities > 



{ for Font Manager } 



FMOutPtr = •FMOutPut; 



FMOutPut = packed record 

errNum: Integer; 

fontflandle: Handle; 

bold: Byte; 

italic: Byte; 

ulOffset: Byte; 

ulShadow: Byte; 

ulThick: Byte; 

shadow: Byte; 

extra: SignedByte; 

ascent: Byte; 

descent: Byte; 

widMax: Byte; 

leading: SignedByte; 

unused: Byte; 

numer: Point; 

denom: Point; 
end; 



FontRec = record 



fontType: 


Integer; 


{ 


font type > 


firstChar: 


Integer; 


{ 


ASCII code of first character } 


lastChar: 


Integer; 


{ 


ASCII code of last character } 


WidMax: 


Integer; 


{ 


maximum character width } 


kernMax: 


Integer; 


{ 


negative of maximum character kern > 


nDescent: 


Integer; 


i 


negative of descent } 


fRecttfidth: 


Integer; 


{ 


width of font rectangle } 


fRectHeight: 


Integer; 


i 


height of font rectangle > 


oHTLoc: 


Integer; 


i 


offset to offset/width table > 


ascent: 


Integer; 


i 


ascent > 


descent: 


Integer; 


i 


descent > 


leading: 


Integer; 


i 


leading > 


rowWords: 


Integer; 


{ 


row width of bit image / 2 > 



bitlmage: arraytl. .rowHords,!. .fRectHeight] of Integer; 

locTable: array[firstChar. .lastChar+El of Integer; 

owTable: array [firstChar. .lastChar+2] of Integer; 

widthTable: array [firstChar. .lastGhar+2] of Integer; 



402 



Turbo Pascal for the Macintosh 



heightTable: arraylfirstChar. .lastChar+21 of Integer; > 
end; 



ffidthTable ^ packed record { 

tabData: array [1. 

tabFont: Handle; 

sExtra: Longint; 

style: Longint; 

fID: Integer; 

fSize; Integer; 

face: Integer; 

device: Integer; 

vInScale: Fixed; 

hInScale: Fixed; 

aFID: Integer; 

fHand: Handle; 

usedFan: Boolean; 

aFace: Byte; 

vOutput: Integer; 

hOutput: Integer; 

vFactor: Integer; 

hFactor: Integer; 

aSize: Integer; 

tabSize: Integer; 
end; 



new lEflK ROM } 

E5t] of fixed; { character widths } 
{ font record used to build table } 
{ extra space used for table } 
{ extra due to style } 
{ font family ID > 
{ font size reguest } 
{ style (face) reguest > 
{ device requested > 



{ actual font family ID for table > 

{ family record used to build up table } 

{ used fixed point family widths > 

{ actual face produced } 

{ vertical scale output value > 

{ horizontal scale output value } 

{ vertical scale output value } 

{ horizontal scale output value > 

{ actual size of actual font used > 

{ total size of table } 



FMetricRec = 



record 
ascent: 
descent: 
leading: 
widHax: 
wTabHandle: 

end; 



Fixed; { baseline to top } 

Fixed; { baseline to bottom } 

Fixed; { leading between lines } 

Fixed; { maximum character width > 

Fixed; { handle to font width table > 



WidTable - record 

numWidths: Integer; { number of entries - 1 > 
{ widList: array [1. .numWidths 1 of HidEntry > 
end; 

HidEntry = record 

widStyle: Integer; { style entry applies to } 

{ widRec: array t f irstChar. .lastChar] of Integer ) 
end; 



AsscEntry = record 

fontSize: Integer; 
fontstyle: Integer; 
fontID: Integer; 
end; 



{ font resource ID } 



FontAssoc 



StyleTable 



record 

numAssoc: Integer; { number of entries - 1 > 

{ asscTable: array [1. .numAssoc] of AsscEntry > 
end; 



record 
fontClass: 
offset: 
reserved: 
indexes : 

end; 



Integer; 
Longint; 
Longint; 

array [Q.. ^7] of Byte; 



NameTable = record 

stringCount: Integer; 
baseFontName: STRaSB; 

{ strings: array [5. .stringCount] of string > 
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{ the lengths of the strings are arbitrary } 
end; 



KernPair = record 

kernFirst: 
kernSecond: 
kernWidth: 
end; 



Char; { 1st character of kerned pair } 
Char; { End character of kerned pair > 
Integer; { kerning in I pt fixed format > 



KernEntry = record 

kernLength: Integer; { length of this entry } 
kernStyle: Integer; { style the entry applies to } 
{ kernRec: arrayCl. .(kernLength/-^)-13 of KernPair > 
end; 

KernTable « record 

nunKerns: Integer; { number of kerning entries > 
{ kernList: array[l. .numKernsJ of KernEntry } 
end; 



FanBec 



record 

ff Flags: 
ffFamID: 
ffFirstChar: 
ffLastChar: 
ff ascent: 
ff Descent: 
ff Leading: 
ffWidMax: 
ffWTabOff: 
ffKernOff: 
ffStylOff: 
ff Property: 
fflntl: 
ff Version: 
{fffissoc: 
{ffWidthTab: 
{ffStyTab: 
{ffKernTab: 
end; 



Integer; 
Integer; 
Integer; 
Integer; { 
Integer; { 
Integer; 
Integer; 
Integer; 
Longint; 
Longint; 
Longint; { 
array[l..S] 
array[1..2] 
Integer; 
FontAssoc;} 
tfidTable;} 
StyleTable; 
KernTable;} 



flags for family > 
family ID number } 
ASCII code of 1st character } 
ASCII code of last character > 
maximum ascent for 1 pt font > 
maximum descent for 1 pt font > 
maximum leading for 1 pt font } 
maximum widMax for 1 pt font } 
offset to width table > 
offset to kerning table } 
offset to style mapping table } 
of Integer; { style property info } 
of Integer; { for international use } 
{ version number } 

{ font association table } 

{ width table > 
} {style mapping table } 

{ kerning table } 



{ for Event Manager > 

{the Event Record is defined in Oslntf> 

KeyMap = packed array[D. .127] of Boolean; 



tfindowPtr 

tfindowPeek 

ControlHandle 



GrafPtr; 
"tfindowRecord; 
"Control? tr; 



HindowRecord = record 

port: 

windowKind: 

visible: 

hilited: 

goAwayFlag: 

spareFlag: 

strucRgn: 

contRgn: 

updateRgn: 

windowDefProc: 

dataHandle: 

titleHandle: 

titletfidth: 

ControlList: 

nextKindov: 



{ for Window Manager } 
{ for Control Manager > 



Graf Port; 

Integer; 

Boolean; 

Boolean; 

Boolean; 

Boolean; 

RgnHandle; 

RgnHandle; 

RgnHandle; 

Handle; 

Handle; 

StrlngHandle; 

Integer; 

ControlHandle; 

HindowPeek; 
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windowPic: 
refCon: 
end; 

TEBec » record 

destHect: Rect; 
viewRect: Rect; 
selRect: Rect; 
lineHeight: Integer; 
fontAscent: Integer; 
selPoint: Point; 
selStart: Integer; 
selEnd: Integer; 
active: Integer; 
wordBreak: ProcPtr; 
clikLoop: ProcPtr; 
clickTinie: Longint; 
clickLoc; Integer; 
caretTime: Longint; 
caretState: Integer; 
just: Integer; 
teLength; Integer; 
hText: Handle; 
recalBack: Integer; 
recalLines: Integer; 
clikStuff: Integer; 
crOnly: Integer; 
txFont: Integer; 
txFace: Style; 
txMode: Integer; 
txSize: Integer; 
inPort: GrafPtr; 
highHook: ProcPtr; 
caretHook: ProcPtr; 
nLines: Integer; 
lines tarts: array [0.. 

end; 

TEPtr = *TERec; 
TEHandle = *TEPtr; 



PicHandle; 
Longint; 



{ 



:or TextEdit } 
destination rectangle > 
view rectangle > 
select rectangle } 
current font line height } 
current font ascent } 
selection point (inouseLoc) } 
selection start } 
selection end } 
<>D if active } 
word break routine } 
click loop routine } 
tiie of first click > 
char, location of click > 
time for next caret blink } 
on/active Booleans > 
fill style } 
length of text below > 
handle to actual text > 
<>0 if recal in background > 
line being recal'ed } 
click stuff (internal) } 
set to -1 if CR line breaks only > 
text Font } 
text Face > 
text Hode > 
text Size > 
Grafport > 
highlighting hook > 
highlighting hook } 
number of lines > 
ItDDD] of Integer; 

{ actual line starts itself > 
{ record > 



CharsHandle « *CharsPtr; 
CharsPtr « "^Chars; 

Chars = packed arrayEO. .320003 of Char; 

{ for Resource Manager } 

ResType = packed array[l..^] of Char; 

{ for Control Manager > 
ControlPtr = *ControlRecord; 



ControlRecord 



packed record 

nextControl: 
contrlOwner: 
contrlRect: 
contrlVis: 
contrlHilite: 
contrlValue: 
contrlMin: 
contrlMax: 
contrlDefProc: 
contrlData: 
contrlAction: 
contrlrfCon: 
contrlTitle: 
end; 



ControlHandle; 

WindowPtr; 

Rect; 

Byte; 

Byte; 

Integer; 

Integer; 

Integer; 

Handle; 

Handle; 

ProcPtr; 

Longint; 

Str255; 

{ ControlRecord > 
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{ for Dialog Manager > 
DialogPtr^ HindowPtr; 
DialogPeek= *DialogRecord; 
DialogRecord= record 

window: ffindowRecord; 

Iteos: Handle; 

textH: TEHandle; 

editField: Integer; 

editOpen: Integer; 

aDefltem: Integer; 
end; 

DialogTHndl' *DialogTPtr ; 
DialogTPtr= *DialogTeittplate; 
DialogTenplate^' record 

boundsRect: Rect; 
procID: Integer; 
visible: Boolean; 
fillerl: Boolean; 
goAwayFlag: Boolean; 



refCon: 
ItemsID: 
title: 
end; 



LongInt; 
Integer; 
StrESB; 



StageList= 



packed record 


boldltin^: 


D..1; 


boxDrwn<: 


Boolean; 


sounds: 


D..3; 


boldltma: 


0..X; 


boxDrwnB: 


Boolean; 


soundB: 


D..3; 


boldItfli2: 


D..1; 


boxDrwnE: 


Boolean; 


soundE: 


a. .3; 


boldltnil: 


D..1; 


boxDrwnl: 


Boolean; 


soundl: 


D..3; 


end; 





AlertTHndl= 
AlertTPtr= 



*fllertTPtr; 
"AlertTemplate; 



aiertTeiBplate= record 

boundsRect: Rect; 
itemsID: Integer; 
stages: StageList; 
end; 



{ for Menu Manager } 
MenuPtr « *HenuInfo; 
HenuHandle = *MenuPtr; 
Henulnfo = record 

menuld: Integer; 
menutfidth: Integer; 
menuHeight: Integer; 
menuProc: Handle; 
enableFlags: LongInt; 
menuData: Str255; 
end; 



{ for Scrap Manager > 
ScrapStuff = record 

scrapSize: LongInt; 

scrapHandle: Handle; 

scrapCount: Integer; 
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scrapState: Integer; 
scrapName: StringPtr; 
end; 

pScrapStuff » *ScrapStuff; 
{ general utilities > 

function BitAnd(longl,long5: Longint): Longint; inline $EDlF,$CD9F,$EEflD; 
function BitOr(longl,longE: Longint): Longint; inline $aDlF/$flDSF,$aEflD; 
function BitXor(longl,long5: Longint): Longint; inline $EDliF,$EE'^F,$BlR7; 
function BitNot{long: Longint): Longint; inline $EERF,$<b'^?; 
function BitShift(long: Longint; count: Integer): Longint; inline $Afl5C; 
function BitTst(bytePtr: Ptr; bitNum: Longint): Boolean; inline $Afl5D; 
procedure BitSetjbytePtr: Ptr; bitNum: Longint); inline $Afl5E; 
procedure BitClrfbytePtr: Ptr; bitNum: Longint); inline $ftfl5F; 
procedure LongMul(a/b: Longint; var dst: Intt^Bit); inline Sftflt?; 
function FixMul(a,b: Fixed): Fixed; inline SAfltfl; 
function FixRatio(numer,denora: Integer): Fixed; inline SftfltR; 
function FixRoundjx: Fixed): Integer; inline lAfltC; 

procedure PackBits(var srcPtr,dstPtr: Ptr; srcBytes: Integer); inline $fiflCF; 
procedure UnPackBits(var srcPtr,dstPtr: Ptr; dstBytes: Integer); inline SAflDD; 
function SlopeFromAngle( angle: Integer): Fixed; inline $AflBC; 
function AngleFromSlope(slope: Fixed): Integer; inline $AflC4; 
function DeltaPoint(ptA,ptB: Point): Longint; inline SAR-^F; 

function NewString(theString:StrE55): StringHandle; inline $ARDfe; 
procedure SetString(theString:StringHandIe; strNew: StrE55); inline $ARD7; 
function GetString(stringID: Integer): StringHandle; inline $ARBA; 
procedure 6etIndString(var theString: strE55; strListID: Integer; 
index: Integer); external; 

function Hunger (h: Handle; offset: Longint; ptrl: Ptr; lenl: Longint; 

ptrE: Ptr; lenE: Longint): Longint; inline $A'1ED; 

function GetIcon(iconID: Integer): Handle; inline $ARBB; 
procedure PlotIcon(theRect: Rect; thelcon: Handle); inline $AR^B; 
function GetCursor(cursorlD: Integer): CursHandle; inline $ARBR; 
function GetPattern(patID: Integer): PatHandle; inline $ARBfl; 
function GetPicturejpicID: Integer): PicHandle; inline $ARBC; 
procedure GetIndPattern(var thePat: Pattern; patListID: Integer; 
index: Integer); external; 

procedure ShieldCursor(shieldRect: . Rect; offsetPt: Point); inline $Afl55; 
procedure ScreenRes(7ar scrnHRes, scrnVRes: Integer); external; 

{ for Font Manager > 

procedure InitFonts; inline $AfiFE; 

procedure GetFontName(faiiiilyID: Integer; var theName: StrEB5); inline SAfiFF; 

procedure GetFNum(theName: StrE55; var familylD: Integer); inline $ARDD; 

procedure SetFontLock(lockFlag: Boolean); inline $ARD3; 

function FMSwapFont(inRec: FHInput): FMOutPtr; inline $ASD1; 

function RealFont(famID: Integer; size: Integer): Boolean; inline $ARDE; 

{ new lEflK ROM > 

procedure SetFScaleDisable{scaleDisable:Boolean) ; inline $Afl3^; 
procedure SetFractEnable (fractEnable: Boolean ) ; external; 
procedure FontMetrics(var theMetrics:FHetricRec) ; inline $Afl35; 

{ for Event Manager } 

function EventAvail(mask:Integer; var theEvent: EventRecord) : 

Boolean; inline $AR71; 
function GetNextEvent(mask: Integer; var theEvent: EventRecord): 

Boolean; inline $AS7D; 
function StillDown: Boolean; inline $AR73; 
function HaitHouseUp: Boolean; inline $AR77; 
procedure GetBouse(var pt: Point); inline $AR?E; 
function TickCount: Longint; inline $AR75; 
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function Button: Boolean; inline $AS7<; 
procedure GetKeys(var k: keyMap); inline $A*17t; 

function GetDblTime: Longint; inline $EEBfl, $OeFD; 
function GetCaretTiae: Longint; inline $2£Bfl/ $QEF^; 

{ for Window Manager > 

procedure Clipftb07e( window: WlndowPeek); inline $RRDB; 

procedure PaintOne( window: WindowPeek; clobbered: RgnHandle); inline IftSOC; 

procedure PaintBehind(starttfindow: HindowPeek; clobbered: RgnHandle); inline Sft^OD; 

procedure Sa7e01d(window: ffindowPeek); inline $aSDE; 

procedure DrawNew(window: WindowPeek; fUpdate: Boolean); inline IftSDF; 

procedure CalcVis( window: WindowPeek); inline $RROH; 

procedure CalcVisBehind(startWindow: WindowPeek; clobbered: RgnHandle); inline $&^DA; 

procedure ShowHide( window: WindowPtr; showFlag: Boolean); inline lA^Dfl; 

function CheckUpdate(var theEvent: ErentRecord) : Boolean; inline 
procedure GetWMgrPort(var wPort: GrafPtr); inline 

?rocedure InitWindows; inline $AR1E; 
unction NewWindow(wStorage: Ptr; boundsRect: Reel; title: StrE55; 

visible: Boolean; theProc: Integer; behind: WindowPtr; 
goAwayFlag: Boolean; refCon: Longint): WindowPtr; inline $Aqi3; 

procedure DisposeWindow(theWindow: WindowPtr); inline $AR1^; 

procedure CloseWindow(theWindow: WindowPtr); inline SAHED; 

procedure MoveWindow(theWindow: WindowPtr; h,v: Integer; BringToFront: 

Boolean); inline $AS1B; 
procedure SizeWindow(theWindow: WindowPtr; width, height: Integer; 

f Update: Boolean); inline $AS1D; 
function GrowWindow(theWindow: WindowPtr; startPt: Point; bBox: Rect): 

Longint; inline SA'IEB; 
procedure DragWindow(theWindow: WindowPtr; startPt: Point; 

boundsRect: Rect); inline $AS55; 
procedure ShowWindow(theWindow: WindowPtr); inline $ASL5; 
procedure HideWindow(theWindow: WindowPtr); inline $ARLb; 
procedure SetWTitle(theWindow: WindowPtr; title: StrE55); inline SA'^IA; 
procedure GetWTitle(theWindow: WindowPtr; var title: StrESE); inline $AR1H; 
procedure HiliteWindow(theW.indow: WindowPtr; fHiLite: Boolean); inline $AR1C; 
procedure Beginnpdate(theWindow: WindowPtr); inline $AREE; 
procedure EndUpdate(theWindow: WindowPtr); inline $ARE3; 
procedure SetWRefCon(theWindow: WindowPtr; data: Longint); inline $AR16; 
function GetWRefCon(theWindow: WindowPtr): Longint; inline $AR1?; 
procedure SetWindowPic(theWindow: WindowPtr; thePic: PicHandle); inline SA'^EE; 
function GetWindowPic(theWindow: WindowPtr): PicHandle; inline $AREF; 
procedure BringToFront (theWindow: WindowPtr); inline $h^^U] 
procedure SendBehind(theWindow,behindWindow: WindowPtr); inline $ARE1; 
function FrontWindow: WindowPtr; inline $ARE^; 
procedure SelectWindow( theWindow: WindowPtr); inline $AR1F; 
function TrackGoaway( theWindow: WindowPtr; thePt: Point): Box)lean; inline $AR1E; 
procedure DrawGrowIcon(theWindow: WindowPtr); inline $ARD^; 

procedure ValidRect(goodRect: Rect); inline SA'^EA; 
procedure ValidRgn(goodRgn: RgnHandle); inline $ARER; 
procedure InvalRect(badRect: Rect); inline $AREfl; 
procedure InvalRgn(badRgn: RgnHandle); inline $ARE7; 
function FindWindow(thePoint: Point; 

var theWindow: WindowPtr): Integer; inline $AREC; 
function GetNewWindow(windowID: Integer; wStorage: Ptr; 

behind: WindowPtr): WindowPtr; inline SARBD; 
function PinRect(theRect: Rect; thePt: Point): Longint; inline $AR^E; 
function DragGrayRgn(theRgn: RgnHandle; startPt: Point; boundsRect, 

slopRect: Rect; axis: Integer; actionProc: ProcPtr): 
Longint; inline SARDS; 



408 



Turbo Pascal for the Macintosh 



{ new lEflK ROM > 

function TrackBox{theWindow:ffindowPtr; thePt:Point; 

partCode: Integer): Boolean; inline $ftfi3B; 

procedure ZooiiiHindow(theWindow:WindowPtr; partCode: Integer; 

front: Boolean); inline $Afl3A; 

i for TextEdit } 

procedure TERctivate( h: TEHandle ); inline $R'^Dfl; 
procedure TECalText( h: TEHandle ); inline SA^DO; 

procedure TEClick( pt: Point; extend: Boolean; h: TEHandle ); inline $ARD4; 

procedure TECopy( h: TEHandle ); inline SAHDS; 

procedure TECut( h: TEHandle ); inline SA^Dt; 

procedure TEDeActivate( h: TEHandle ); inline $A9DR; 

procedure TEDelete( h: TEHandle ); inline $ASD?; 

procedure TEDispose( h: TEHandle ); inline $ARCD; 

procedure TEIdle( h: TEHandle ); inline SARDA; 

procedure TEInit; inline WCQ; 

procedure TEKey( key: Char; h: TEHandle ); inline SA^DC; 

function TENew( dest, view: Eect ): TEHandle; inline $ARDE; 

procedure TEPaste( h: TEHandle ); inline $ARDB; 

procedure TEScroll( dh, dv: Integer; h: TEHandle ); inline $ASDD; 

procedure TESetSelect( selStart, selEnd: LongInt; h: TEHandle ); inline $ARD1; 

procedure TESetText( inText: Ptr; textLength: LongInt; h: TEHandle ); inline $ASCF; 

procedure TEInsert( inText: Ptr; textLength: LongInt; h: TEHandle ); inline SASDE; 

procedure TEnpdate( rUpdate: Rect; h: TEHandle ); inline $A<1D3; 

procedure TESetJust( just: Integer; h: TEHandle ); inline $ARDF; 

function TEGetText( h: TEHandle ): CharsHandle; inline $AqCB; 

function TEScrapHandle: Handle; inline $EEBfl, $DAB<; 
function TEGetScrapLen: LongInt; external; 

Procedure TESetScrapLen( length: LongInt); external; 
unction TEFrom Scrap: OsErr; external; 
function TEToScrap: OsErr; external; 

procedure SettfordBreak(wBrkProc: ProcPtr; hTE: TEHandle); external; 
procedure SetClikLoop(clikProc: ProcPtr; hTE: TEHandle); external; 

{ new laflK ROM > 

procedure TESelView(hTE: TEHandle); inline $AflU; 

procedure TEPinScroll(dh,dv:Integer; hTE : TEHandle ) ; inline $AfllE; 

procedure TEAutoView{ auto: Boolean; hTE : TEHandle ) ; inline $Afll3; 

{ box drawing utility > 

procedure TextBox{ inText: Ptr; textLength: LongInt; 

r: Rect; style: Integer ); inline $ARCE; 

{ for Resource Manager > 

function InitResources: Integer; inline SAR^S; 

procedure RsrcZonelnit; inline $AS=lb; 

procedure CreateResFile(fileNaine: StrESS); inline SARBl; 

function OpenResFile(fileNaine: StrE55): Integer; inline $Aqq7; 

procedure UseResFile{refNuni: Integer); inline lARRfl; 

function GetResFileAttrs(refNuro: Integer): Integer; inline $ARFt; 

procedure SetResFileAttrs(refNuin: Integer; attrs: Integer); inline $ARF?; 

procedure apdateResFile(refNuni: Integer); inline $ARSR; 

procedure CloseResFlle(refNuni: Integer); inline $ARRA; 

procedure SetResPurge( install: Boolean); inline $ARR3; 

procedure SetResLoad(AutoLoad: Boolean); inline $ARqB; 

function CountResources(theType: ResType): Integer; inline $ARRC; 

function GetIndResource(theType: ResType; index: 

Integer): Handle; inline SARRD; 
function CountTypes: Integer; inline $ARRE; 

procedure GetIndType(var theType: ResType; index: Integer); inline $ARRF; 
function UniqueID( theType: ResType): Integer; inline $ARC1; 
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function GetResource ( theType : ResType ; ID : I n teger ) : 

Handle; inline %mU; 
function GetNanedResourcel theType: ResType; name: Str255): 

Handle; inline $A9A1; 
procedure LoadResource(theResource: Handle); inline $A9ftE; 
procedure ReleaseResource{theResource: Handle); inline $ASa3; 
procedure DetachResource(theResource: Handle); inline $AR^E; 
procedure ChangedResource(theResource: Handle); inline $ARAA; 
procedure tfriteResource{theResource: Handle); inline $A9BD; 
function HonieResFile(theResource: Handle): Integer; inline $ARA<; 
function CurResFile: Integer; inline $A'^R^; 
function GetResAttrs(theResource: Handle): Integer; inline lARAt; 
procedure SetResAttrs{theResource: Handle; attrs: Integer); inline $AqA7; 
procedure 6etResInfo{theResource: Handle; var thelD: Integer; 

?ar theType: ResType; var name: StrESE); inline $ARAfl; 
procedure SetResInfo(theResource: Handle; thelD: Integer; 

name: StrESS); inline $AW; 
procedure AddResource(theResource: Handle; theType: ResType; 

thelD: Integer; name: StrE55); inline $A9AB; 
rocedure RmveResource(theResource: Handle); inline SA^AD; 
unction SizeResource(theResource: Handle): Longint; inline $ARA5; 
function ResError: Integer; inline $ARAF; 

{ new lEflK ROM } 

function GetlIndResource( theType: ResType; index: Integer): Handle; inline $AAOE; 
function CountlTypes: Integer; inline lAfllC; 

function GetlResource( theType: ResType; thelD: Integer): Handle; inline $AfilF; 
function GetlNamedResource(theType: ResType; name: StrEBE): Handle; inline lAflSD; 
procedure GetllndType (var theType: ResType; index: Integer); inline $A60F; 
function UniquelID(theType: ResType): Integer; inline SAfllQ; 
function CountlResources( theType: ResType): Integer; inline $AflDD; 

function HaxSizeRsrc (theResource: Handle) : Longint; inline $AfiEl; 
function RsrcHapEntry( theResource: Handle): Longint; inline $A^C5; 
function OpenRFPerm{fileName: StrESS; VRefMum: Integer; permission: Byte): 
Integer; inline $ARC^; 

{ for Control Manager } 

function NewControl(curWindow: windowPtr; boundsRect: Rect; title: StrESS; 

visible: Boolean; value: Integer; rain: Integer; 

max: Integer; contrlProc: Integer; refCon: Longint): 

ControlHandle; inline $A^5^; 
procedure DisposeControl(theControl: ControlHandle); inline $A^5S; 
procedure KillControls{theHindow: ffindowPtr); inline lARSt; 

procedure MoveControl(theControl: ControlHandle; h,v: Integer); inline SA^SR; 
procedure SizeControl(theControl: ControlHandle; w,h: Integer); inline $AR5C; 
procedure DragControl(theControl: ControlHandle; startPt: Point; 

bounds: Rect; slopRect: Rect; axis: Integer) ; inline $ASt7; 
procedure ShowControl{theControl: ControlHandle); inline $AS57; 
procedure HideControl{theControl: ControlHandle); inline lARSfl; 
procedure SetCTitle(theControl: ControlHandle; title: StrESS); inline $AR5F; 
procedure GetCTitle(theControl: ControlHandle; var title: StrESS); inline $AR5E; 
procedure HiliteControl(theControl: ControlHandle; hiliteState: 
Integer); inline $ARSD; 

rocedure SetCRefCon(theControl: ControlHandle; data: Longint); inline $AS5B; 

unction GetCRefConjtheControl: ControlHandle): Longint; inline $ARSA; 

?rocedure SetCtlValue(theControl: ControlHandle; theValue: Integer); inline $ARt3; 
unction GetCtlValue(theControl: ControlHandle): Integer; inline lARtO; 

function GetCtlMin(theControl: ControlHandle): Integer; inline $ARbl; 
function GetCtlHax(theControl: ControlHandle): Integer; inline $ARtE; 
procedure SetCtlMin(theControl: . ControlHandle; theValue: Integer); inline $ARt4; 
procedure SetCtlMax(theControl: ControlHandle; theValue: Integer); inline $ARtS; 
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function GetCtlAction(theControl: ControlHandle) : ProcPtr; inline $ARbR; 
procedure SetCtiaction(theControl: ControlHandle; newProc: ProcPtr); inline $ARtB; 

function TestControl(theControl: ControlHandle; thePt: Point): 

Integer; inline SARtid; 
function TrackControl(theControl: ControlHandle; thePt: Point; 

actionProc: ProcPtr): Integer; inline $ARtfl; 

function FindControl(thePoint: Point; theWindow: WindowPtr; var theControl: 
ControlHandle): Integer; inline $ASbC; 

rocedure DrawControls(theWindotf : tfindowPtr); inline $AStR; 

unction GetNewControl{controlID: Integer; owner: WindowPtr): 
ControlHandle; inline $ARBE; 

{ new lEflK RON } 

procedure UpdtControl(theKindow: WindowPtr; updateRgn:RgnHandle) ; inline $AS53; 
{ for Dialog Manager } 

procedure InitDialogs(resunieProc: ProcPtr); inline $AR7B; 
function GetNewDialog(dialogID: Integer; wStorage: Ptr; 

behind: WindowPtr): DialogPtr; inline $AS7C; 
function NewDialog( wStorage: Ptr; boundsRect: Rect; title: StrEBS; 

visible: Boolean; theProc: Integer; behind: WindowPtr; 

goRwayFlag: Boolean; refCon: LongInt; itmLstHndl: Handle): 

DialogPtr; inline $AR7D; 
function IsDialogEvent(event: EventRecord) : Boolean; inline 
function DialogSelect( event: EventRecord; var theDialog: DialogPtr; 

var itemHit: Integer): Boolean; inline SA'^flO; 
procedure ModalDialog( filterProc: ProcPtr; var itemHit: Integer); inline SARRl; 
procedure DrawDialog(theDialog: DialogPtr); inline $A9fll; 
procedure CloseDialog (theDialog: DialogPtr); inline $ARflE; 

Procedure DisposDialog( theDialog: DialogPtr); inline $ASfi3; 
unction Alert (alertID: Integer; filterProc: ProcPtr): Integer; inline SARfiS; 
function StopAlert(alertID: Integer; filterProc: ProcPtr): Integer; inline SARflt; 
function NoteAlertjalertlD: Integer; filterProc: ProcPtr): Integer; inline $ARfl7; 
function CautionAlert(alertID: Integer; filterProc: ProcPtr): 

Integer; inline SARflfl; 
procedure CouldAlert(aIertID: Integer); inline $ARfiS; 
procedure FreeAlert(alertID: Integer); inline $ARflA; 
procedure CouldDialog(DlgID: Integer); inline $AS71; 
procedure FreeDialog(DlgID: Integer); inline $fiR7A; 
procedure ParaniText(citeD, citel, citeE, cite3: StrSSS); inline SA'lflB; 
procedure ErrorSound( sound: ProcPtr); inline $ARflC; 
procedure 6etDIteni( theDialog: DialogPtr; iteniNo: Integer; 

var kind: Integer; var item: Handle; 
var box: Rect); inline SA^flD; 
procedure SetDItem(dialog: DialogPtr; itemNo: Integer; kind: Integer; 

item: Handle; box: Rect); inline lARflE; 
procedure SetIText(item: Handle; text: StrESS); inline $ASflF; 
procedure GetlTextfitem: Handle; var text: StrE55); inline $ASSD; 
procedure SelIText( theDialog: DialogPtr; itemNo: Integer; 

startSel, endSel: Integer ); inline $Aq7E; 

{ routines designed only for use in Pascal > 
function GetAlrtStage: Integer; inline $3EBfl/ $DARA; 
procedure ResetAlrtStage; inline $^E?6, $DARA; 

procedure DlgCut(theDialog: DialogPtr); external; 
procedure DlgPaste{theDialog: DialogPtr); external; 
procedure DlgCopy(theDialog: DialogPtr); external; 
procedure DlgDelete(theDialog: DialogPtr); external; 

procedure SetDAFont(fontNum: Integer); inline $31DF/ $DAFA; 

{ new lEflK ROM } 

procedure HideDItem (theDialog :DialogPtr; itemNo : Integer ) ; inline $AflE7; 
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procedure ShowDIteia{theDialog:DialogPtr; itemNo : Integer ) ; inline $Afl2fi; 
procedure DpdtDialog(theDialog:DialogPtr; updateRgnrRgnHandle) ; inline $ftR7fl; 
function FindDIteiii{theDialog:DialogPtr; thePt: Point): Integer; inline lARfl^; 

{ for Desk Manager } 

function SystemE vent (myE vent: EventRecord) : Boolean; inline $ARB2; 

procedure SysteiiClick(theEvent: EventRecord; theWindow: windowPtr); inline $ARB3; 

procedure SystemTask; inline $ftSB<; 

procedure SysteiiiHenu(iiienuResult: Longlnt); inline $flRB5; 

function SystemEditjeditCode: Integer): Boolean; inline $AqC2; 

function OpenDeskAcc(theAcc: StrE55): Integer; inline $ARBt; 

procedure CloseDeskAcc(refNttiB: Integer); inline $A<1B7; 

{ for Menu Manager > 

Procedure InltMenus; inline $AS3D; 
unction NewMenu(inenuID: Integer; menuTitle: StrESB): menuHandle; inline $AR31; 
function GetMenu(rsrcI0: Integer): MenuHandle; inline $ARBF; 
procedure DisposeHenu(nienu: menuHandle); inline %AH32\ 
procedure AppendHenu(Hienu: menuHandle; data: str255); inline $AR3a; 

procedure InsertMenu (lenu: MenuHandle; beforeld: Integer); inline $A135; 
procedure DeleteHenu (inenuld: Integer); inline $ARB(i; 
procedure DravMenuBar; inline $AS3?; 
procedure ClearHenuBar; inline $A<13<; 

function GetMenuBar: Handle; inline 

function GetNewflBar(iiienuBarID: Integer): Handle; inline lAICD; 
procedure SetHenuBar(nenuBar: Handle); inline $AR3C; 

function MenuSelect(startPt: Point): Longlnt; inline $AR3D; 
function MenuKey(ch: CHAR): Longlnt; inline $AS3E; 
procedure HiLiteHenu(inenuId: Integer); inline $AR3fl; 

procedure Setlteni(menu: menuHandle; item: Integer; itemString: 

StrE55); inline $Aq4?; 
procedure Getltera(menu: menuHandle; item: Integer; 

var itemString: Str255); inline $AR<t; 
procedure Enableltem(menu: menuHandle; item: Integer); inline $AR3R; 
procedure Disableltem{menu: menuHandle; item: Integer); inline $AR3A; 
procedure Checkltem(menu: menuHandle; item: Integer; checked: 

Boolean); inline $AR45; 

procedure SetItemIcon(menu: menuHandle; item: Integer; iconNum: Byte); inline $AR^D; 
procedure GetItemIcon(menu: menuHandle; item: Integer; 

7ar iconNum: Byte); inline $AR3F; 
procedure SetItemStyle(menu: menuHandle; item: Integer; styleVal: Style); external; 
procedure GetItemStyle(raenu: menuHandle; item: Integer; 

var StyleVal: Style); external; 
procedure SetItemMark(menu: menuHandle; item: Integer; markChar: CHAR); inline 

procedure GetItemMark(menu: menuHandle; item: Integer; 

var markChar: CHAR); inline $AR<3; 
procedure SetMenuFlash(flashCount: Integer); inline $ARa; 
procedure FlashMenuBarjmenuID: Integer); inline $AR^C; 

function GetMHandle(menuID: Integer): menuHandle; inline $RS^S; 
function CountMIteis(menu: menuHandle): Integer; inline $AH5D; 
procedure AddResMenu{menu: menuHandle; theType:ResType) ; inline $AS4D; 
procedure InsertResMenu(menu: menuHandle; theType:ResType; 

afterltem: Integer); inline $AR51; 
procedure CalcMenuSize(menu:menuHandle) ; inline $AR^fi; 

{ new 12fiK ROM > 

procedure InsMenuItem ( theMenu : Menuhandle ; 

itemString: Str555; afterltem : Integer ) ; inline $AflEt; 
procedure DelHenuIteiQ(theHenu: MenuHandle; item : Integer) ; inline $AS5a; 
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{ for Scrap Manager > 

function GetScrap{ hDest: Handle; what: ResType; 

?ar offset: Longint ): Longint; inline $ftRFD; 
function InfoScrap: pScrapStuff; inline $ARFR; 
function LoadScrap: Longint; inline $RRFB; 
function PatScrap{ length: Longint; what: ResType; 

source: Ptr ): Longint; inline lA^FE; 
function UnloadScrap: Longint; Inline SA'IFA; 
function ZeroScrap: Longint; inline IftRFC; 

{ package manager } 

procedure InitAIlPacks; inline SA^^Gt; 

procedure InitPack(packID: Integer); inline $ARE5; 
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Packages are sets of data structures and routines that are stored as resources in 
the SYSTEM file and brought into memory only when needed. They serve as 
extensions to the Toolbox and Mac OS; the most useful (and most commonly 
used) is the Standard File Package, which brings up the standard Mac dialog box 
to open files or select a file name for output. Other packages include Disk Initial- 
ization, International Utilities, and Binary-Decimal Conversion. 

unit Packlntf(-ID); 
Interface 



uses MemTypes , QuickDraw , Osl ntf , Toollntf ; 
{ disk initialization package 



} 



procedure DILoad; external; 
procedure DIUnLoad; external; 

function DIBadMount(where: Point; evtMessage: Longint): Integer; external; 

function DIFormat{drvNuin: Integer): OsErr; external; 

function DIVerify(drvNuin: Integer): OsErr; external; 

function DIZeroCdrvNum: Integer; volName: StrEBS): OsErr; external; 



{ standard file package 

const 

putDlgID = -3m; i SFPutFile dialog template ID } 

putSave =1; { save button } 

putCancel = E; { cancel button } 

putEject =5; { eject button } 

putDrive = £>; { drive button } 

putName = ?; { editTExt iten for file naiie > 

getDlgID = -^DDD; i SFGetFile dialog template ID } 



} 



getOpen 

getCancel 

getEject 

getDrive 

getRmList 

getScroll 

type 

SFReply 



1; { open button } 

3; { cancel button } 

5; { eject button } 

t; { drive button } 

7; { userltem for file name list 

fi; { userltem for scroll bar > 



record 

good: Boolean; 
copy: Boolean; 
fType: OsType; 
vRefNum: Integer; 
version: Integer; 
fName: String [^3]; 
end; 



{ ignore comniand if False > 

{ not used > 

{ file type or not used } 

{ volume reference number } 

{ file's version number } 

{ file name > 
{ SFReply } 



SFTypeList = array[D..3] of OSType; 

procedure SFPutFile (where: Point; prompt: Str555; origName: StrESS; 

dlgHook: ProcPtr; var reply: SFReply); external; 
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procedure SFPPutFile{where: Point; prompt: StrESB; origName: StrE55; 

dlgHook: ProcPtr; var reply: SFReply; dlglD: Integer; 

filterProc: ProcPtr); external; 
procedure SFGetFile( where: Point; prompt: StrE55; fileFilter: ProcPtr; 

numTypes: Integer; typeList: SFTypeList; dlgHook: ProcPtr; 

var reply: SFReply); external; 
procedure SFPGetFlle( where: Point; prompt: StrE55; fileFilter: ProcPtr; 

numTypes: Integer; typeList: SFTypeList; dlgHook: ProcPtr; 

var reply: SFReply; dlglD: Integer; filterProc: ProcPtr); 

external; 

{ international utilities package } 

const 



{ constants for manipulation of international resources > 
{ masks used for setting and testing currency format flags > 
currSymLead = lb; { set if currency symbol leads r reset if trails > 
currNegSym = 3E; { set if minus sign for negative num, reset if parentheses > 
currTrailingZ = t<; { set if trailing zero > 
currLeadingZ = lEfl; < set if leading zero > 



{ constants specifying absolute value of short date form } 
MDY ' D; { month, day, year > 

DMI « 1; { day, month, year > 

YMD = E; { year, month, day } 

{ masks used for date element format flags } 
dayLdingZ = 3E; { set if leading zero for day } 

mntLdingZ = { set if leading zero for month } 

century = lEfl; { set if century, reset if no century > 

{ masks used for time element format flags } 
secLeadingZ = 3E; { set if leading zero for seconds } 
minLeadingZ = hA\ { set if leading zero for minutes } 
hrLeadingZ = lEfl; { set if leading zero for hours > 

{ country codes for version numbers > 



verOS 
verFrance 
verBritain 
verGermany 
verltaly 
verNetherlands 
verBelgiumLux 
verSweden 
verSpain 
verDenmark 
verPortugal 
verFrCanada 
verNorway 
verlsrael 
verJapan 
verAustralia 
verRrabia 
verFinland 
verPrSwiss 
verGrSwiss 
verGreece 
verlceland 
verMalta 
verCyprus 
verTurkey 
verYugoslavia 
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type 



intlDHndl - "intlDPtr; 
intlQPtr - "intlDRec; 
IntlDRec » packed record 

decimalPt: Char; 

thousSep: Char; 

listSep: Char; 

currSyml: Char; 

currSymE: Char; 

currSyin3: Char; 

currFmt: Byte; 

dateOrder: Byte; 

shrtDateFiat: Byte; 

dateSep: Char; 

timeCycle: Byte; 

timeFmt: Byte; 

mornStr: packed array [1. 



.A] 



eveStr: packed array El..<] 



tiraeSep: Char; 
timelSuff: Char; 
timeESuff: Char; 
tinie3Suff: Char; 
time^Suff: Char; 
tiraeSSuff: Char; 
tinietiSuff: Char; 
tiine7Suff: Char.; 
tiraeflSuff: Char; 
metricSys: Byte; 
intlDVers: Integer; 
end; {intlDRec) 

intllHndl = *intllPtr;, 
intllPtr = *intllREc; 
intllRec = packed record 

days: arraytl..?] of 

months: array[l..lE] 

suppressDay: Byte,; 

IngDateFint: Byte; 

dayLeadingD: Byte; 

abbrLen: Byte; 

stD: packed arraytl.. 

stl: packed arraytl.. 

stE: packed arraytl.. 

st3: packed arraytl.. 

stA: packed arraytl.. 

intllVers: Integer; 

localRtn: Integer; 



end; 



{ ASCII character for decimal point > 

{ ASCII character for thousand separator > 

{ ASCII character for list. separator > 

{ ASCII for currency symbol . (3 bytes long) > 



< currency format flags } 
{ short date form - DHYJMD, or m } 
i date elements format flag > 
{ ASCII for. date separator } 
{ indicates 12 or hr cycle > 
{ time elements format flags > 
of Char; 

{ ASCII for trailing string from 0:DD to ll:5q > 
of Char; 

{ ASCII for trailing string from 1S:DD to .23:5^ } 
{ ASCII for the time separator > 
{ suffix string used in 2A hr mode } 
{ fi characters long > 



{ indicates metric or English system } 

{ version: high byte * country, low byte - vers > 



StringtlS]; { length and word for Sun through Mon } 
of String[153; { length and word for Jan to Dec } 

{ D for day of week, E55 for no day of week > 
{ expanded date format D or E55 } 
{ ESS for leading D, D for no leading Q } 
i length of abbreviated names in long form } 
A] of Char; { the string stD } 
A] of Char; { the string stl > 
A] of Char; { the string stE } 
A) of Char; { the string st3 > 
A] of Char; { the string st^ > 
{ version word > 
{ routine for localizing mag comp; > 
{ minimal case is $<E75 for RTS, but } 
{ routine may be longer than one integer } 
{ intllRec > 



DateForm = (shortDate, longDate, abbrevDate); 



function IUGetIntl(theID: Integer): Handle; external; 

procedure lUSetlntlfrefNum: Integer; thelD: Integer; intlParam: Handle); external; 
procedure IUDateS.tring(dateTime: Longint; longFlag: DateForm; 

var result: StrESS); external; 
procedure IUDatePString(date!Eiffle: Longint; longFlag: DateForm; 

var result: StrESS; intlParam: Handle); external; 
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procedQie inTiineString(dateTiine: Longlnt; wantSeconds: Boolean; 

var result: StrESS); external; 
procedure IUTiiiiePString(dateTiiiie: Longlnt; wantSeconds; Boolean; 

var result: Str555; intlParam: Handle); external; 
fanctlon lUHetric: Boolean; eiteraal; 
futtction IDCoiiipStrlng(aStr,bStr: StrasS): Integer; external; 
function IUEqualString(aStr,bStr: StrE55): Integer; external; 
function IUMagString(aPtr,bPtr: Ptr; aLen,bLen: Integer): Integer; external; 
function inMagIDString(aPtr,bPtr: Ptr; aLen,bLen: Integer) :Integer; external; 

{ binary-decimal conversion package > 

procedure StringToNuin(theString: StrESS; var theNum: Longlnt); external; 
procedure NumToStringf theNum: Longlnt; var theString: StrESS); external; 

{ list manager >. 
const 



{ for list manager > 

{ masks for selection flags (selFlags) > 

LOnlyOne = -lEfl; { D = multiple selections/ 1 « one } 

LExtendDrag * t^; { 1 * drag select without shift key } 

LNoDisjoint = 3E; { 1 = turn off selections on click } 

LNoExtend = It; { 1 = don't extend shift selections > 

LNoRect = fl; < 1 = don't grow (shift/ drag) selection as rect } 

LUseSense = ^; { I = shift should use sense of start cell } 

LNoNilHilite = E; { 1 = don't highlight empty cells } 

{ masks for other flags (listFlags) } 



LDoVAutoscroll 
LDoHftutoscroll 



2; 
1; 



{ 1 = allow vertical autoscroUing } 
{ 1 = allow horizontal autoscroUing } 



i messages to list definition procedure > 



LInitMsg 
LDrawMsg 
LHiliteMsg 
LCloseHsg 



D; 
1; 

E; 

3; 



{ tell drawing routines to init themselves > 

i draw (and de/select) the indicated data > 

{ invert highlight state of specified cell > 

{ shut down, the list is being disposed > 



type 

Cell = Point; 



dataftrray = packed array [D..3E0D0] of Char; 
dataPtr = '*dataRrray; 
dataHandle = *dataPtr; 



ListPtr ' *ListRec; 
ListHandle = '^ListPtr; 
ListRec = record 

rView: Rect; 

port: Graf Ptr; 

indent: Point; 
cellSize: Point; 

visible: Rect; 

vScroU: ControlHandle; 
hScroU: ControlHandle; 

selFlags: SignedByte; 
LActive: Boolean; 
LReserved: SignedByte; 
listFlags: SignedByte; 



{ Rect in which we are viewed } 

{ Grafport that owns us } 

{ Indent pixels in cell > 

{ Cell size } 

{ visible row/column bounds > 

{ vertical scroll bar (or. NIL) } 

{ horizontal scroll bar (or NIL) > 

{ defines selection characteristics. > 

{ active or not } 

{ internally used flags .> 

{ other flags } 
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clikTiie: Longint; { save tirae of last click > 

clikLoc: Point; i save position of last click } 

mouseLoc: Point; i current mouse position } 

LClikLoop: Ptr; < routine called repeatedly during ListClick > 

lastClick: Cell; { the last cell clicked in > 

refCon: Longint; { reference value } 

listDefProc: Handle; { handle to the defProc > 

userHandle: Handle; { general purpose handle for user } 

dataBounds: Rect; { total number of rows/columns > 

cells: dataHandle; { handle to data> 

naxindex: Integer; { index past the last element > 

cellArray: array of Integer; { offsets to elements } 

end; 

procedure LActivate( act: Boolean; IHandle: ListHandle ); external; 
function LAddColumn( count, colNum: Integer; IHandle: ListHandle ): 

Integer; external; 
function LAddRov( count, rowNum: Integer; IHandle: ListHandle ): 

Integer; external; 
procedure LAddToCell( dataPtr: Ptr; dataLen: Integer; theCell: Cell; 

IHandle: ListHandle ); external; 
procedure LAutoScroll( IHandle: ListHandle ); external; 
procedure LCellSize( cSize: Point; IHandle: ListHandle); external; 
function. LClick( pt: Point; modifiers: Integer; IHandle: ListHandle ): 

Boolean; external; 
procedure LClrCell( theCell: Cell; IHandle: ListHandle ); external; 
procedure LDelColumn(countr coINum: Integer; IHandle : ListHandle) ; external; 
procedure LDelRow(count, rowNum: Integer; IHandle: ListHandle); external; 
procedure LDispose( IHandle: ListHandle ); external; 
procedure LDoDraw( drawit: Boolean; IHandle: ListHandle ); external; 
procedure LDraw( theCell: Cell; IHandle: ListHandle ); external; 
procedure LFind{ var offset, len: Integer; theCell: Cell; 

IHandle: ListHandle ); external; 
procedure LGetCell( dataPtr: Ptr; var dataLen: Integer; theCell: Cell; 

IHandle: ListHandle ); external; 
function LGetSelect ( next: Boolean; var theCell: Cell; 

IHandle: ListHandle): Boolean; external; 
function LLastClick { IHandle: ListHandle ): Longint; external; 
function LNew( rView, databounds: Rect; cSize: Point; theProc: 
Integer; thetfindow: ffindowPtr; 
drawit, hasGrow,scrollHoriz,scrollVert: 
Boolean): ListHandle; external; 
function LNextCell( hNext,vNext: Boolean; var theCell: Cell; 

IHandle: ListHandle): Boolean; external; 
procedure LRect( var cellRect: Rect; theCell: Cell; 

IHandle: ListHandle ); external; 
procedure LScroll( dRows, dCols: Integer; IHandle: ListHandle ); external; 
function LSearch( dataPtr: Ptr; dataLen: Integer; SearchProc: Ptr; 

var theCell: Cell; IHandle: ListHandle): Boolean; external; 
procedure LSetCell( dataPtr: Ptr; dataLen: Integer; theCell: Cell; 

IHandle: ListHandle ); external; 
procedure LSetSelect( setit: Boolean; theCell: Cell; 

IHandle: ListHandle ); external; 
procedure LSize{ listWidth,listHeight: Integer; IHandle: ListHandle); external; 
procedure Lnpdate( theRgn: RgnHandle; IHandle : ListHandle; external; 
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MacPHnt 



The MacPrint unit provides access to the Macintosh Printing Manager. The 
Printing Manager is a set of RAM-based data types and routines that allow you to 
use standard QuickDraw routines to print text or graphics on a printer. These 
provide a device-independent interface to printer drivers, which enable you to 
print on a specific device (Image Writer, LaserWriter, and other printers). One 
(or more) of these printer drivers — usually found in the SYSTEM folder — must 
be available in order to use this package. 

unit MacPrint (-11); 
interface 

uses MemTypes, QuickDraw, OSIntf,ToolIntf; 



const 

iPrPgFract 



15D; 



IPrPgFst = 1; 
iPrPgMax « qq^R; 

iPrRelease = 3; 

iPfMaxPgs = lEfl; 

{ driver constants > 
iPrBitsCtl = A; 
IScreenBits* $DDDDDDOD; 
IPaintBits - IDDDDDDOl; 
lHiScreenBits= lODOODDlD; 
IHiPaintBits = $DD0DDD11; 
iPrlOCtl 



iPrEvtCtl 
IPrEvtRll 
IPrEvtTop 
iPrDevCtI 
IPrReset 
IPrPageEnd 



5; 

SQODEFFFD; 
SOQDIFFFD; 

$Q0D1DD00; 

IDDDaODDO; 



lPrLineFeed= $00030000; 

IPrLFSixth = $00D3FFFF; 

lPrLFEighth= $DGD3FFFE; 

iFMgrCtl - fl; 



{ Page scale factor; } 

{ ptPgSize (below) is in units of 1/iPrPgFract > 
{ page range constants } 



{ current version number of the code. > 
{ DC 7/E3/a< > 

{ nax number of pages in a print file. } 



{ Bitnap print proc's ctl number } 

{ Bitmap print proc's screen bitmap paran } 

{ Bitmap print proc's paint Esq pix] parani } 

{ Bitmap print proc's screen Bitmap param > 

{ Bitmap print proc's paint Esq pix] param > 

{ raw byte 10 proc's ctl number > 

{ PrEvent proc's ctl number > 

{ PrEvent proc's CParam for the entire screen } 

{ PrEvent proc's CParam for the top folder > 

{ PrDevCtl proc's ctl number } 

{ PrDevCtl proc's CParam for reset > 

{ PrDevCtl proc's CParam for end page } 

{ PrDevCtl proc's CParam for paper advance } 

{ PrDevCtl proc's CParam for 1/tth inch paper advance } 
{ PrDevCtl proc's CParam for 1/flth inch paper advance > 

{ FMgr's Tail-hook Proc's ctl number } 

{ [The Pre-Hook is the status call] } 



{ error constants: > 
iMemFullErr - -IDA; 
iPrftbort = lafl; 
ilOftfeort - -E?; 

{ PrVars lo mem area: } 
pPrGlobals = SODOOOq^^; 
bDraftLoop = 0; 
bSpoolLoop = 1; 
bDserlLoop = B; 
bUserELoop - 3; 

{ currently supported printers: > 

bDevCItoh - 1; iDevCItoh - $0100; { CItoh > 
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bDevDaisy = E; iDevDaisy = $DEDD; { Daisy > 
bDevLaser = 3; iDevLaser * $D3DD; { Laser > 



type 



TPRect 
TPBitMap 



*Rect; 
•BitMap; 



{ A Rect Ptr > 
{ A BitMap Ptr } 



{ NOTE: Changes will also affect: PrEqu, TCiVars & TPfVars } 



TPrVars ^ record 

iPrErr: Integer; 
bDocLoop : S ignedBy te ; 



bUserl: 
lUserl: 
lUserE: 
lUser3: 
end; 

TPPrVars = 



SignedByte; 
Longint; 
Longint; 
Longint; 



{ A longs for printing; } 

{ see SysEqu for location > 

{ current print error; } 

{ set to iPrAbort to abort printing > 

{ Doc style: Draft/ Spoolr and ..> 

{ currently use low 2 bits; > 

{ the upper ^ are for flags > 

{ spares used by the print code > 



*TPrVars; 



TPrlnfo = record 



iDev: 
iVRes: 
iHRes: 
rPage: 
end; 

TPPrlnfo = 



Integer; 
Integer; 
Integer; 
Rect; 

"TPrlnfo; 



{ print info record: } 
{ the parameters needed for page composition > 

< font mgr/QuickDraw device code } 

< resolution of device, in device coordinates > 
{ ..note: V before H => compatible with point > 

{ page (printable) rectangle in device coordinates } 



{ types of paper feeders > 

TFeed = ( feedCut, feedFanfold, feedMechCut, feedOther 



); 



TPrStl = record { printer style: the printer configuration } 

{ and usage information } 

{ device (driver) number: } 

{ Hi byte=RefNuffl, Lo byte=variant } 

{ fD « fHiRes, fl « fPortrait, f2 - fSqPix, } 

{ f3 - fExZoom, f4 = fScroll } 

{ paper size in units of 1/iPrPgFract > 

{ NOTE: V before H => compatible with Point > 

SignedByte; { 10 port number. Refnum? > 

{ paper feeder type } 



wDev: Integer; 



iPageV: Integer; 
iPageH: Integer; 



bPort: 
feed: 

end; 

TPPrStl = 



TFeed; 
*TPrStl; 



{ Banding data structures. Not of general interest to Apps. > 
TScan * { band scan direction: Top-Bottom/ Left-Right, etc. > 

( scanTB/ scanBT/ scanLR, scanRL ); 



TPrXInfo = record 
iRowBytes: Integer; 
iBandV: Integer; 
iBandH: Integer; 
iDevBytes: Integer; 
iBands: Integer; 



bPatScale: 
bULThick: 
bULOffset: 
bULShadow: 

scan: 
bXInfoX: 



SignedByte; 

SignedByte; 
SignedByte; 
SignedByte; 

TScan; 
SignedByte; 



{ print time extra information > 

{ band's rowBytes > 

{ size of band/ in device coordinates } 

{ NOTE: V before H compatible with Point > 

{ size for allocation; may be more than rBounds! 

{ number of bands per page > 

{ pattern scaling > 

{ three underscoring parameters > 



{ band scan direction > 
{ an extra byte } 
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end; 

TPPrXInfo = *TPrXInfo; 



TPrJob record 

iFstPage: Integer; 

iLstPage: Integer; 

iCopies: Integer; 

bJDocLoop: SignedByte; 

fFromOsr; Boolean; 

pIdleProc: ProcPtr; 

pFileName: StringPtr; 

iFileVol: Integer; 

bFileVers: SignedByte; 

bJobX: SignedByte; 
end; 

TPPrJob ' *TPrJob; 
TPrint = record 



iPrVersion: 


Integer; 


{ 


2 


> 


Prinfo: 
} 


TPrlnfo; 


{ 


lA 


} 


rPaper: 


Beet; 


{ 


fl 


} 


PrStl: 


TPrStl; 


{ 


a 


> 


PrInfoPT: 


TPrlnfo; 


{ 


lA 


> 


PrXInfo: 


TPrXInfo; 


{ 


ih 


} 


PrJob: 


TP r Job; 


i 


ED 


} 






{ 


fiE 


> 



{ print job: } 

{ Print "form" for single print request > 

{ page range } 

{ number copies > 

{ doc style: Drafts Spool, and .. } 

{ printing from an user's app (not PrApp) flag ) 

{ Proc called while waiting on 10/ etc. > 

{ spool file name: NIL for default. } 

{ spool file vol: set to D initially } 

{ spool file version: set to 0 initially > 

{ an extra byte > 



{ Theuniversal lEO byte printing record > 
{ printing software version } 
{ Prinfo data associated with the current 



{ paper rectangle [offset from rPagel } 

{ print request's style } 

{ print time imaging metrics } 

{ print time (expanded) print info record } 

{ print job request > 

{ total of above: lED - flS = 3a bytes 



of Integer; { spare to fill to lEO bytes > 



needed to fill lED } 

PrintX: array [1.. IT] 
end; 

TPPrint = *TPrint; 
THPrint = "TPPrint; 

i Printing Graf Port, fill printer imaging, whether spooling, banding, etc., 
happens "thru" a GrafPort } 

TPrPort = record { this is the "PrPeek" record > 



GPort: 


GrafPort; 


{ 


GProcs: 


QDProcs; 


{ 


IGParaml: 


Longint; 


{ 


IGParaiE: 


Longint; 




lGParam3: 


Longint; 




IGParaml: 


Longint; 




fOurPtr: 


Boolean; 


{ 


fOurBits: 


Boolean; 


{ 



.and its procs } 
{ It bytes for private parameter storage > 



end; 

TPPrPort 



*TPrPort; 



TPrStatus = record { print 

iTotPages: Integer; 

iCurPage: Integer; 

iTotCopies: Integer; 

iCurCopy: Integer; 

iTotBands: Integer; 

iCurBand: Integer; 

fPgDirty: Boolean; 

f Imaging: Boolean; 

hPrint: THPrint; 

pPrPort: TPPrPort; 

hPic: PicHandle; 
end; 

TPPrStatus = "TPrStatus; 



status: print information during printing > 

{ total pages in print file > 

{ current page number } 

{ total copies requested } 

{ current copy number } 

{ total bands per page } 

{ current band number } 

{ True if current page has been written to > 

{ set while in band's DrawPic call } 

i handle to the active printer record } 

{ Ptr to the active PrPort } 

{ handle to the active picture > 



{ PicFile = a TPfHeader followed by n QuickDraw Pics (whose PicSize is invalid!)} 
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TPfPgDir = 
iPages: 
IPgPos: 

end; 

TPPfPgDir « 
THPfPgDir - 



recorcl 
Integer; 
array CO.. 

*TPfPgDir; 
*TPPfPgDir; 



iPfMaxPgsl of Longint; 



TPfHeader = record 

Print: TPrint; 

PfPgDir: TPfPgDir; 
end; 

TPPfHeader = *TPfHeader; 
THPfHeader = "TPPfHeader; 



{ print file header > 



{ NOTE: Type conipatible with an hPrint } 



{ This is the Printing Dialog Record. Only used by folks appending their own 
dialogs. } 

Print Dialog: The dialog stream object > 



TPrDlg 
Dig: 



record { 

DialogRecord; 
pFltrProc: ProcPtr; 
pltemProc: ProcPtr; 
hPrintasr: THPrint; 
fDoIt: Boolean; 
fDone: Boolean; 
lUserl: Longint; 
lOsere: Longint; 
lUser3: Longint; 
lUser^: Longint; 



{ the dialog window } 

{ the filter proc. > 

{ the item evaluating proc. 

{ the user's print record > 



{ ^ longs for users to hang global data > 



end; 

TPPrDlg 



Plus more stuff needed by the particular printing dialog > 
*TPrDlg; { == a dialog ptr } 



{ — init— > 

procedure PrOpen; external? 

{ Open the .Print driver, get the Current Printer's Esrc file > 
{ name from SysRes, open the resource file, and open the .Print 
{ driver living in SysRes. PrOpen BUST be called during init time. } 

procedure PrClose; external; 

{ Closes JUST the print rsrc file. Leaves the .Print driver in SysRes open. > 

{ —Print Dialogs t, Default— } 

procedure PrintDefault ( hPrint: THPrint ); external; 

{ defaults a handle to a default print record. > 

{ NOTE: You allocate (or fetch from file's resources..) the handle, } 

{ I fill it. Also, I may invoke this at odd times whenever I think > 

{ you have an invalid Print record! } 

function PrValidate ( hPrlnt: THPrint ): Boolean; external; 

{ Checks the hPrint. Fixes it if there has been a change in } 

{ Sff version or in the current printer. Returns fChanged. } 

{ NOTE: Also updates the various parameters within the Print } 

{ record to match the current values of the PrStl 4 PrJob. } 

{ It does NOT set the fChanged result if these parameters > 

{ changed as a result of this update. } 



function PrStlDialog { hPrint: THPrint ) 
function PrJobDialog { hPrint: THPrint ) 
{ The dialog returns the fDoIt flag: 
If PrJobDialog( . . ) then begin 
PrintMyDoc {..); 
SaveMyStl {..) 

end 

or 

if PrStlDialog{..) then SaveMyStl ( 



Boolean; external; 
Boolean; external; 
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{ NOTE: These may change the hPrint** if the version number 
is old or the printer is not the current one. } 

procedure PrJobMerge (hPrintSrc, hPrintDst: THPrint); external; 

{ Merges hPrintSrc's PrJob into hPrintDst [Source/Destination], 
allows one job dialog being applied to several docs [Finder printing] > 

{ —The Document printing procs: These spool a print file.— > 

function PrOpenDoc ( hPrint: THPrint; 

pPrPort: TPPrPort; 
pIOBuf: Ptr ): TPPrPort; external; 

{ Set up a graf port for Pic streaming and make it the current } 
{ port. Init the print file page. directory. Create and open the > 
{ print file. hPrint: The print info. pPrPort: the storage to } 
{ use for the TPrPort. If nil we allocate. pIOBuf: an 10 buf; > 
{ if nil, file sys uses volume buf. returns TPPrPort: The TPPrPort > 
{ {graf port) used to spool thru. > 

procedure PrCloseDoc ( pPrPort: TPPrPort ); external; 

{ Write the print file page directory. Close the print file. } 

procedure PrOpenPage ( pPrPort: TPPrPort; pPageFrame: TPRect ); external; 

{ If current page is in the range of printed pages: Open a picture > 
{ for the page. Otherwise set a null port for absorbing an image. } 
{ pPageFranie := PrInfo.rPage/ unless you're scaling. Set pPageFranie > 
{ to nil unless you want to perfori PicScaling on the printer. } 
{ [The printing procs will call OpenPicture (pPageFrame*) and > 
{ DrawPicture (hPic, rPage); ] NOTE: Use of QuickDraw may now } 
{ cause File I/O errors due to our Pic spooling! } 

procedure PrClosePage( pPrPort: TPPrPort ); external; 

{ Close & kill the page picture. Update the file page directory. } 
{ If we allocated the TPrPort then de-allocate it. > 

{ —The "Printing Application" proc: Read and band the spooled PicFile.— > 

procedure PrPicFile( hPrint: THPrint; 

pPrPort: TPPrPort; 
pIOBuf: Ptr; 
pDevBuf: Ptr; 
var PrStatus: TPrStatus ); external; 

{ Read and print the spooled print file. } 
{ The idle proc is run during imaging and printing. } 

{ —Get/Set the current Print Error— } 

function PrError: Integer; external; 

procedure PrSetError ( iErr: Integer ); external; 

{ —The .Print driver calls.— > 

procedure PrDrvrOpen; external; 

procedure PrDrvrClose; external; 

{ Open/Close the .Print driver in SysRes. Make it purgable or not. > 

{ ONLY used by folks doing low-level stuff, not full document printing. > 

procedure PrCtlCall (itfhichCtl: Integer; IParaml, IParamE/ IParamB: Longint); 
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external; 

{ R generalized Control proc for the Printer driver. } 

{ The main use is for bitmap printing: 

PrCtlCall (iPrBitsCtl, pBitMap, pPortRect, IControl); 

procedure PrBits ( pBitMap: Ptr; —QuickDraw bitmap 

pPortRect: TPRect; —a portrect. 

* use bounds for whole bitmap « 
IControl: Longint ); — 0=>Screen resolution/Portrait 
This dumps a bitmap/portrect to the printer. 
IControl is a device dep param; use D for screen res/portrait/etc. 
Each different printer will use IControl parameter differently. 
Thus PrCtlCall (iPrBitsCtl, ©MyPort'^.ScreenBits, @MyPort*.PortRect. Bounds, D) 
performs a screen dump of just my port's data. 

Two special control calls are included in the driver for screen 

printing from the key board: 

PrCtlCall (iPrEvtCtl, IPrEvtRll, D, 0); Prints the screen 
PrCtlCall (iPrEvtCtl, IPrEvtTop, D, 0); Prints the top folder 

These are handled by the system for keyboard access but can be 

called by anyone at any time. They can be very cheap printing for 

ornaments, for example! 

Another useful call is used for sending raw data to the printer: 
PrCtlCall (iPrlOCtl, pBuf, IBufCount, pIdleProc); > 

{ — Semiprivate stuff— } 

function PrStllnit { hPrint: THPrint ): TPPrDlg; external; 

function PrJoblnit ( hPrint: THPrint ): TPPrDlg; external; 

function PrDlgMain { hPrint: THPrint; pDlglnit: ProcPtr ): Boolean; external; 

procedure PrCfgDialog; external; 
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FixMath 



The FixMath unit is a collection of types and functions that implement fixed- 
point real numbers. This unit is very useful for applications that require real 
numbers but don't need the accuracy of floating-point math. Fixed-point opera- 
tions run much faster than regular floating point, so you can choose precision 
over increased speed. 

unit FixMath ( -IE); 

{ These calls support three types of fixed point numbers / each 3d bits long. > 
{ The bits are interpreted as shown. The '-' represents the sign bit. > 

Type < Integer Portion > < Fractional Portion > 

Longint -xxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx. 

Fixed >xxxxxxx xxxxxxxx. xxxxxxxx xxxxxxxx 

Fract -X. xxxxxxxx xxxxxxxx xxxxxxxx xxxxxx 

{ Type Longint can represent integers between +/-E1^7^fl3fc^7. Type Fixed can > 
{ represent fractional quantities between +/-3E?tfl/ to about 5 digits of > 
{ accuracy. Type Fract can represent fractional quantities between to > 
{about R digits of accuracy. These numeric representations are useful for > 
{ applications that do not^ require the accuracy of the floating-point routines > 
{ and need to run as fast as possible. The Graf 3D three-dimensional > 
{ graphics package resides on top of these routines. Although FixMul is in the } 
{ file ToolTraps/ it is listed below to show how it handles different types. > 
i Additional fixed point routines are described in the Inside Macintosh chapter, } 
{ "Toolbox Utilities" > 

Interface 

uses HenTypes; 

type Fract * Longint; 

{ These routines are only available on a system with a ISflK ROM: > 

function LongEFix(x:longint) :Fixed; inline $Afi3F; 

function Fix5Long(x:fixed) iLonglnt; inline $Afl<D; 

function FixEFrac (x: fixed ): Fract; inline $Afl^l; 

function FracEFix (x: fract) :Fixed; inline $Afl<E; 

{ Functions to convert between fixed-point types } 

function FixEX(x:fixed) :Extended; Inline $Afl<3; 

function XEFixj x: extended) : Fixed; inline $Afl^^; 

function FracEX(x: fract): Extended; inline $Afl^5; 

function XEFrac( x: extended ):Fract; inline $Afl<tj; 

{ Functions to convert between fixed, fract, and the extended } 
{ floating-point type > 

function FixAtanE(x,y:LongInt):Fixed; inline lAfllfl; 
{ FixATanE returns the arctangent of y / x. Note that FixATanE effects 
"arctan(type / type) ~> Fixed": 

arctan(LongInt / Longint) — > Fixed 

arctan(Fixed / Fixed ) ~> Fixed 

arctan( Fract / Fract ) ~> Fixed } 
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{ The following routines are supplied as glue code: > 

function FracMul(x, y: Fract): Pract; external; 
{ Fracflul returns x * y. 
Note that FracHul effects "type « Fract — > type": 
Fract * Fract — > Fract 

Longlnt ♦ Fract — > Longint 

Fract * Longlnt . — > Longlnt 
Fixed * Fract — > Fixed 

Fract » Fixed — > Fixed > 



function FixDiv(x, y: Fixed): Fixed; external; 



{ FixDi? returns x / y. 
Note that FixDiv effects "type / type — > 
Fixed / Fixed ~> Fixed 

Longlnt / Longlnt — > Fixed 

Fract / Fract — > Fixed 

Longlnt / Fixed — > Longlnt 



Fixed" 



Fract / Fixed 



— > Fract > 



function FracDiv(x, y: Fract): Fract; external; 

{ FracDiv returns x / y. Note that FracDiv effects "type / type — > Fract": 



Fract / Fract 




Fract 


Longlnt / Longlnt. 


— > 


Fract 


Fixed / Fixed 


— > 


Fract 


Longlnt / Fract 


— > 


Longlnt 


Fixed / Fract 


— > 


Fixed > 



function FracSqrt(x: Fract): Fract; external; 
{ FracSqrt returns the square root of x. Both argument and result > 
{ are regarded as unsigned } 

function FracCos(x: Fixed): Fract; external; 
function FracSin(x: Fixed): Fract; external; 

i FracCos and FracSin return the cosine and sine, respectively, } 

{ given the argument x in radians > 
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GrqfSD 



GrafHD is a RAM-based, three-dimensional graphics package that sits on top of 
QuickDraw, It implements 3-D GrafPorts and provides a complete set of 3-D 
operations, including rotation, translation, scaling, and clipping. 

unit Graf3D(-13); 
interface 

nses NenTypes/ QuickDraw, FixMath; 

const radConst « 3754q3t; {radConst = 5?.5q5?a> 

type Point3D=record 
x: fixed; 
y: fixed; 
z: fixed; 
end; 

Point2D*record 

x: fixed; 
y: fixed; 
end; 

Xf Matrix = array [ D. .3, 0. .31 of fixed; 
Port3DPtr « "PortBD; 
Port3D « record 

GrPort: GrafPtr; 

viewRect: Reel; 

xLef t / y Top , xRight / yBottom : fixed ; 

pen/penPriine,eye: PointBD; 

hSize,vSize: fixed; 

hCenter,7Center: fixed; 

xCotan,yCotan: fixed; 

ident: Boolean; 

xForai; Xf Matrix; 

end; 



var thePort3D: Port3DPtr; 



procedure InitGrfBD 
procedure Open3DPort 
procedure SetPort3D 
procedure GetPort3D 



procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 



MoveToED 

MoveTo3D 

LineToED 

LineTo3D 

MoveSD 

Move3D 

LineSD 

Line3D 



procedure Viewport 

procedure LookAt 

procedure ViewAngle 

procedure Identity; 

procedure Scale 

procedure Translate 



(globalPtr: Ptr); external; 
(port: Port3DPtr); external; 
(port: Port3DPtr); external; 
(var port: Port3DPtr); external; 

(x,y: fixed); external; 
(x,y,z: fixed); external; 
(x,y: fixed); external; 
(x,y,z: fixed); external; 
(dx,dy: fixed); external; 
(dx,dy,dz: fixed); external; 
(dx,dy: fixed); external; 
(dx/dy,dz: fixed); external; 

(r: Beet); external; 

(left, top, right, bottom: fixed); external; 

(angle: fixed); external; 

external; 

(xFactor,yFactor,zFactor: fixed); external; 
(dx,dy,dz: fixed); external; 
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procedure Pitch (xftngle: fixed); external; 

procedure Yaw (yAngle: fixed); external; 

procedure Roll (z Angle: fixed); external; 

procedure Skew (zAngle: fixed); external; 

procedure TransForra (src: Point3D; var dst: Point3D); external; 

function Clip3D (srcl,src5: Point3D; ?ar dstl/dstS: Point): Boolean; 

external ; 

procedure SetPt3D (var pt3D: Point3D; XrY,z: fixed); external; 

procedure SetPtSD (var ptED: PointSD; x,y: fixed); external; 
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AppleTalk 



AppleTalk is the Macintosh local-area network; that is, the means by which you 
connect a group of Macs with printers, disks, other devices, and each other. The 
AppleTalk Manager is used to communicate with devices connected to an 
AppleTalk network. See Chapter 7 for more details on using this unit. 

unit AppleTalk 

Interface 

uses Hemtypes, QuickDraw, OSIntf; 

const 

lapSize = 20; 
ddpSize = Eb; 
nbpSize = at; 
atpSize » Bt; 

{ error codes } 

ddpSktErr = -91; 

ddpLenErr = -S2; 

noBridgeErr = -R3; 

LRPProtErr = -HA; 

excessCoUsns « -R5; 

nbpBuffOvr « -102^; 

nbpNoConfirin = -1DE5; 

nbpConfDiff = -lOEt; 

nbpDuplicate = -1057; 

nbpNotFound = -lOEfl; 

nbpNISErr = -lOER; 

reqFailed = -10*1t; 

tooManyReqs « -1QR7; 

tooManySkts = -IDRfl; 

badATPSkt = -lORR; 

badBuffNum = -HOD; 

noRelErr = -1101; 

cbNotFound = -11D5; 

noSendResp = -1103; 

noDataArea » -110^; 

reqAborted = -1105; 

bufESmallErr = -3101; 

noMPPErr = -310E; 
ckSumErr -3103; 

extractErr = -3104; 

readQErr = -3105; 

atpLenErr = -310t; 

atpBadRsp * -3107; 

recNotFnd = -310fl; 

sktClosedErr = -3109; 

type 

ABByte - 1..1E?; 
STR3E = STRING[3a]; 
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iBCallType « (tLftPRead,tLAPWrite,tDDPRead,tDDPHrite,tNBPLookUp, 

tHBPConfirBi,tNBPRegister,UTPSndBequest,tATPGetRequesti 
UTPSdRsp , t ATPAddRsp i t ATPReques t , t ATPResponse } ; 

ABProtoType « (lapProto,ddpProto,nbpProto,atpProto); 

UPAdrBlock « packed record 

dstHodelD : Byte; 
srcNodelD : Byte; 
LAPProtType : ABByte; 
end; 

AddrBlock - packed record 

aHet : Integer; 
aNode : Byte; 
aSocket : Byte; 
end; 

EntityNaie « record 

objStr : Str35; 
typeStr : Str35; 
zoneStr : Str35; 
end; 

EntityPtr = *EntityNaiiie ; 

RetransType » packed record 

retranslnterval : Byte; 
retransCount : Byte; 
end; 

BltHapType packed array [0..7] of Boolean; 

BDSEleient - record 

Buff Size : Integer; 
BuffPtr : Ptr; 
DataSize : Integer; 
UserBytes : LongInt; 
end; 

BDSType - array CO.. 71 of BDSSlenent; 

BDSPtr * *BDSType; 

ABusRecord = record 

abOpCode : abCallType; 
abResult : Integer; 
abOserReference : LongInt; 

case abProtoType of 
lapProto: 
{lapftddress : LAPAdrBlock; 
lapReqCount : Integer; 
lapActCount : Integer; 
lapDataPtr : Ptr; 

); 

ddpProto: 
(ddpType : Byte; 
ddpSocket : Byte; 
ddpAddress : AddrBlock; 
ddpReqCount : Integer; 
ddpActCount : Integer; 
ddpDataPtr : Ptr; 
ddpNodelD : Byte; 

); 
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nbpProto: 
(nbpEntityPtr : EntityPtr; 
nbpBufPtr : Ptr; 
nbpBufSize : Integer; 
nbpDataField : Integer; 
nbpAddress : AddrBlock; 
nbpRetransmitlnfo : RetransType; 

); 

atpProto: 
(atpSocket ; Byte; 
atpAddress : AddrBlock; 
atpHeqCount : Integer; 
atpDataPtr : Ptr; 
atpRspBDSPtr : BDSPtr; 
atpBitMap : BitMapType; 
atpTransID : Integer; 
atpActCount : Integer; 
atpUserData : LongInt; 
atpXO : Boolean; 
atpEOM : Boolean; 
atpTiieOut : Byte; 
atpRetries : Byte; 
atpNuniBufs : Byte; 
atpNuuRsp : Byte; 
atpBDSSize : Byte; 
atpRspUData : LongInt; 
atpRspBuf : Ptr; 
atpRspSize : Integer; 

); 

end; { record > 

fiBRecPtr = "ABusRecord; 
ABRecHandle = *ABRecPtr; 

function LAPOpenProtocol(theLAPType : ABByte; protoPtr : Ptr) : OSErr; external; 
function LAPCloseProtocol(theLftPType : ABByte) : OSErr; external; 
function LAPRead(abRecord : ABRecHandle; async : Boolean) : OSErr; external; 
function LAPWrite(abRecord : ABRecHandle; async : Boolean) : OSErr; external; 

function LAPRdCancel(abRecord : ABRecHandle) : OSErr; external; 

function DDPOpenSocket(var theSocket : Byte; sktListener : Ptr) : OSErr; external; 
function DDPCloseSocket( theSocket : Byte) : OSErr; external; 
function DDPRead{abRecord : ABRecHandle; retCksuniErrs : Boolean; 
function async : Boolean) : OSErr; external; 

function DDPWrite(abRecord : ABRecHandle; doCheckSum : Boolean; 
async : Boolean) : OSErr; external; 

function DDPRdCancel(abRecord : ABRecHandle) : OSErr; external; 
function 

function NBPLoad : OSErr; external; 
function NBPUnLoad : OSErr; external; 

function NBPLookUp(abRecord : ABRecHandle; async : Boolean) : OSErr; external; 
function NBPConfirni(abRecord : ABRecHandle; async : Boolean) : OSErr; external; 
function NBPRegister(abRecord : ABRecHandle; async : Boolean) : OSErr; external; 
function NBPReroove( entity Name : EntityPtr) : OSErr; external 
function NBPExtract(theBuffer : Ptr; numlnBuf : Integer; whichOne ilnteger; 

var abEntity : EntityName; 

var address : AddrBlock) : OSErr; external; 

function ATPLoad : OSErr; external; 
function ATPUnLoad : OSErr; external; 
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function flTPOpenSocket(addrRcvcl : AddrBlock; var atpSocket : Byte) : OSErr; external; 

function aTPCloseSocket( atpSocket : Byte) : OSErr; external; 
function ATPSndRequest(abBecor,d : ABRecHandle; async : Boolean) : OSErr; external; 
function ATPGetRequest{abRecord : ABRecHandle; async : Boolean) : OSErr; external; 
function ATPSndRsp(abRecord : ABRecHandle; async : Boolean) : OSErr; external; 
function ATPAddRsp(abRecord : ABRecHandle) : OSErr; external. 

function ATPRequest(abRecord : ABRecHandle; async : Boolean) : OSErr; external; 

function ATPResponse(abRecord : ABRecHandle; async : Boolean) : OSErr; external; 

function ATPReqCancel(abRecord : ABRecHandle; async : Boolean) : OSErr; external; 

function ATPRspCancel(abRecord : ABRecHandle; async : Boolean) : OSErr; external; . 

procedure RemovefldlBlocks ; external; 

{ ReuioveHdlBlks is a routine that Is called automatically at the beginning > 
{ of every Pascal call. It checks for free (disposable) memory blocks that } 
{ the interface has allocated and disposes of them. The memory blocks have } 
{ been allocated by the Newflandle call. Most of these memory blocks are } 
{ small (on the order of E0-5D bytes). The user has the option to > 
{ make the call whenever s/he wants to. The general rule is that one memory } 
{ block will be allocated every time a network call is made; and it will } 
{ not be free until the call completes. > 

function GetNodeAddress(var myNode,myNet : Integer) : OSErr; external; 

function MPPOpen : OSErr; external; 
function HPPClose : OSErr; external; 

function IsMPPOpen : Boolean; external; 
function IsATPOpen : Boolean; external; 
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Speechlntf 



The Speechlntf unit provides an interface to MacinTalk, a speech synthesizer 
that runs under Mac OS as a driver. In real time, MacinTalk converts an ASCII 
string of phonetic codes into synthetic speech. MacinTalk uses a special 
program, READER, to convert English text into the phonetic codes used by 
MacinTalk. See Chapter 7 for more details. 

unit Speechlntf (-15); 

Interface 

HeniTypes ; 



uses 



const 
noExcpsFile = "; 
noReader = 'noReader'; 
fullUnitT » -^DOD; 



{ signals reader to use only basic rules } 
{ signals SpeechOn to NOT bring in reader > 
{ error code for driver unit table full } 



type 

SpeechErr 
SpeechRecord 
SpeechPointer 
SpeechHandle 



- Integer; 

= array [D..qq] of Byte; 

= ^SpeechRecord; 

* *SpeechPointer; 



{ Driver parm block, used internally > 
{ pointer to driver parm block 
{ handle to driver parm block 



Sex = (Male, Female); 

FDMode = (Natural, Robotic, NoChange); 

Language = (xEnglish, French, Spanish, Gerian, Italian); 



VoiceRecord 



record 

theSex: 
theLanguage: 
theRate: 
thePitch : 
theMode: 
theName: 
refCon: 
end; 
* VoiceRecord; 



Sex; 

Language; 

Integer; 

Integer; 

FQMode; 

StrE55; 

Longint; 



VoicePtr 
function SpeechOn 

procedure SpeechOff 
procedure SpeechRate 
procedure SpeechPitch 

procedure SpeechSex 

function Reader 

function MacinTalk 



(ExcpsFile: StrE55; 

var theSpeech: SpeechHandle): SpeechErr; external; 

(theSpeech: SpeechHandle); external; 

(theSpeech: SpeechHandle; theRate: Integer); external;. 

(theSpeech: SpeechHandle; thePitch: Integer; 
theMode: FDMode); external; 

(theSpeech: SpeechHandle; theSex: Sex); external; 
{ reserved for future implementation > 

(theSpeech: SpeechHandle; Englishlnput: Ptr; 
InputLength: Longint; PhoneticOutput: Handle): 
SpeechErr; external; 

(theSpeech: SpeechHandle; Phonemes: Handle): 
SpeechErr; external;. 
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SCSUntf 



The SCSUntf unit provides access to the Small Computer Standard Interface 
(SCSI) port found on several models of the Macintosh. It allows you to determine 
what devices are connected to the SCSI port and to communicate with them. 



unit SCSUntf 
Interface 

uses MemTypes /Quickdraw , OSIntf ; 
const 



{ transfer 
scinc 
scNoInc - 
scfidd 
scMove = 
scLoop = 
scNOP - 
scStop = 
scConip = 



instruction operation codes > 



1; 

3; 

fl; 



{ SCINC instruction } 

{ SCNOINC instruction } 

{ SCfiDD instruction } 

{ SCMOVE instruction 

{ SCLOOP instruction 

{ SCNOP instruction 

{ SCSTOP instruction 

{ SCCOMP instruction 



{ SCSI manager result codes } 
scBadParmsErr = 

scCommErr = E; 

scCoropareErr - t; 

scPhaseErr = 5 ; 



{ unrecognized instruction } 

{ breakdown in SCSI protocols } 

{ data comparison error in read } 

{ phase error } 



type 



SCSIInstr 



, record 
scOpcode: 
scParainl: 
scParaniS: 

end; 



Integer; { operation code > 
Longint; { first parameter > 
Longint; { second parameter } 



function SCSIResetiOSErr; external; 

function SCSIGet:OSErr; external; 

function SCSISelect(targetID: Integer) :OSErr; external; 

function SCSICmd(buffer:Ptr; countilnteger) :OSErr; external; 

function SCSIRead(tibPtr:Ptr) :OSErr; external; 

function SCSIRBlind(tibPtr:Ptr):OSErr; external; 

function SCSIWrite(tibPtr:Ptr) lOSErr; external; 

function SCSIffBlind(tibPtr:Ptr):OSErr; external; 

function SCSICofflplete(var stat, messageilnteger; 

wait:LongInt) rOSErr; external; 
function SCSIStat:Integer; external; 
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Macintosh Character Set 



Table E-1 shows the decimal and hexadecimal representations of the Macintosh 
characters. Note, however, that other fonts may produce characters diflFerent 
than those shown in the table. 

Table E-l The Macintosh Character Set 
DEC ilEX CHAR DEC CHAR 



0 


00 


NUL 


1 


01 


SOH 


2 


02 


STX 


3 


03 


ETX 


4 


04 


EOT 


5 


05 


ENQ 


6 


06 


ACK 


7 


07 


BEL 


8 


08 


BS 


9 


09 


HT 


10 


OA 


LF 


11 


OB 


VT 


12 


OC 


FF 



13 


OD 


CR 


14 


OE 


SO 


15 


OF 


SI 


16 


10 


DLE 


17 


11 


DC1 


18 


12 


DC2 


19 


13 


DC3 


20 


14 


DC4 


21 


15 


NAK 


22 


16 


SYN 


23 


17 


ETB 


24 


18 


CAN 


25 


19 


EM 
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DEC HEX CHAR 



26 


1A 


SUB 


27 


IB 


ESC 


28 


10 


PS 


29 


ID 


GS 


30 


IE 


RS 


31 


IF 


US 


32 


20 


SP 


33 


21 


! 


34 


22 




35 


23 


# 


36 


24 


$ 


37 


25 


% 


38 


26 


& 


39 


27 




40 


28 


( 


41 


29 


) 


42 


2A 




43 


2B 


+ 


44 


20 




45 


2D 


■ 


46 


2E 




47 


2F 


/ 


48 


30 


0 


49 


31 


1 


50 


32 


2 


51 


33 


3 


52 


34 


4 


53 


35 


5 


54 


36 


6 


55 


37 


7 


56 


38 


8 


57 


39 


9 



DEC HEX CHAR 



58 3A 

59 3B ; 

60 30 < 

61 3D 

62 3E > 

63 3P ? 

64 40 @ 

65 41 A 

66 42 B 

67 43 0 

68 44 D 

69 45 E 

70 46 P 

71 47 G 

72 48 H 

73 49 I 

74 4A J 

75 4B K 

76 40 L 

77 4D M 

78 4E N 

79 4P O 

80 50 P 

81 51 Q 

82 52 R 

83 53 S 

84 54 T 

85 55 U 

86 56 V 

87 57 W 

88 58 X 

89 59 Y 
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Table E-l The Macintosh Character Set^ continued 





hjcjA, 








KjEUXm. 


90 


5A 


z 


122 


7A 


z 


91 


5B 


I 


123 


7B 


{ 


92 


5C 


\ 


124 


7C 


1 


93 


5D 


1 


125 


7D 


} 


94 


5E 


A 


126 


7E 




95 


5F 




127 


7F 


DEL 


96 


60 




128 


80 


A 


97 


61 


a 


129 


81 


A 


98 


62 


b 


130 


82 


Q 


99 


63 


c 


131 


83 


E 


100 


64 


d 


132 


84 


N 


101 


65 


e 


133 


85 


6 


102 


66 


f 


134 


86 


u 


103 


67 


g 


135 


87 


a 


104 


68 


h 


136 


88 


^ 


105 


69 


i 


137 


89 


a 


106 


6A 


j 


138 


8A 




107 


6B 


k 


139 


8B 


a 


108 


6C 


1 


140 


8C 




109 


6D 


m 


141 


8D 


9 


110 


6E 


n 


142 


8E 


e 


111 


6F 


0 


143 


8F 


e 


112 


70 


P 


144 


90 


e 


113 


71 


q 


145 


91 


e 


114 


72 


r 


146 


92 


1 


115 


73 


s 


147 


93 


1 


116 


74 


t 


148 


94 


1 


117 


75 


u 


149 


95 


1 


118 


76 


V 


150 


96 


n 


119 


77 


w 


151 


97 


6 


120 


78 


X 


152 


98 


6 


121 


79 


y 


153 


99 


0 
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DEC HEX CHAR 



154 


9A 


6 


155 


9B 


d 


156 


9C 


u 


157 


9D 


u 


158 


9E 


u 


159 


9F 


u 


160 


AO 


t 


161 


A1 


o 


162 


A2 


0 


163 


A3 


£ 


164 


A4 


§ 


165 


A5 


• 


166 


A6 


K 


167 


A7 


6 


168 


A8 




169 


A9 


© 


170 


AA 


TM 


171 


AB 




172 


AC 




173 


AD 




174 


AE 


/E 


175 


AF 


0 


176 


BO 


oo 


177 


B1 


± 


178 


B2 


< 


179 


B3 


> 


180 


B4 


¥ 


181 


B5 




182 


B6 


a 


183 


B7 


I 


184 


B8 


n 


185 


B9 





DEC HEX CHAR 



186 


BA 


J 


187 


BB 


a 


188 


BO 


fi 


189 


BD 


Q 


190 


BE 


89 


191 


BP 


0 


192 


CO 


6 


193 


CI 


i 


194 


C2 




195 


C3 




196 


C4 


/ 


197 


C5 




198 


C6 


A 


199 


C7 


« 


200 


C8 




201 


C9 


... 


202 


CA 




203 


CB 


A 


204 


CC 


A 


205 


CD 


0 


206 


CE 


CE 


207 


CP 


oe 


208 


DO 


— 


209 


D1 


— 


210 


D2 




211 


D3 


N 


212 


D4 




213 


D5 




214 


D6 




215 


D7 


0 


216 


D8 


y 


217 


D9 


Y 
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DEC HEX CHAR Bic HEX CHAR 



218 


DA 


/ 


219 


DB 


□ 


220 


DC 


< 


221 


DD 


> 


222 


DE 


fi 


223 


DF 


fl 


224 


EO 


* 


225 


El 


• 


226 


E2 




227 


E3 


ff 


228 


E4 




229 


E5 


A 


230 


E6 


E 


231 


E7 


A 


232 


E8 


E 


233 


E9 


E 


234 


EA 


1 


235 


EB 


1 


236 


EC 


T 



237 


bU 


1 


238 


bb 


O 


239 


br 


A 
O 


240 


rO 


m 


241 


r I 


A 

o 


242 


r2 


u 


243 


r3 


u 


244 


r4 


u 


245 


ETC 

ro 


1 


246 


ro 




247 


r / 




248 


PA 

ro 




249 


PQ 




250 


FA 




251 


FB 


• 


252 


FC 




253 


FD 




254 


FE 




255 


FF 
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Turthgraphics: Mac Graphics Made Easier 



If you want to produce graphics on your Macintosh but don't want to take the 
time to learn the QuickDraw routines, Turtlegraphics is the answer. It's an easy 
graphics program, called Turtle, that's included as part of Turbo Pascal. 

Turbo Pascal Turtlegraphics is based on a concept devised by S. Papert and his 
group at the Massachusetts Institute of Technology. To get around the concept of 
cartesian coordinates, Papert and his colleagues invented the idea of a "turtle" 
that could "walk" a given distance and turn at specified angles, drawing a line as 
it walked along. The simple algorithms in this program can create images that are 
more interesting than those created by algorithms of the same length in cartesian 
coordinates. 

Like the other graphics routines on the Macintosh, Turtle operates in the 
active window. Turtlegraphics, ordinary graphics and even the Turbo Pascal stan- 
dard text output can be used simultaneously, and can share a common window. 

The Turbo Pascal Turtlegraphics routines operate on turtle coordinates. The 
turtle's Home position (0,0) in this coordinate system is always in the middle of 
the active window; positive values stretch to the right (X) and upwards (Y), and 
negative values stretch to the left (X) and downwards (Y): 

The range of coordinates is based on the size of the screen. For a Macintosh 
and Macintosh-f-, these are the values: X =0..511 Y = 0..341. However, the 
actual range is limited to the size of the active window. Coordinates outside the 
active window are legal, but are ignored. This means that drawings are clipped 
to the limits of the active window (unless wrap is on). 
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Following are the 16 Turtlegraphics procedures you can use to create figures. 
Back 

Syntax: Back(Dist); 

Moves the turtle backward by the distance given by the integer expression 
Dist. The turtle moves from its current position in the direction opposite to its 
current heading and draws a line in the current pen color. If Dist is negative, the 
turtle moves forward. 

Clear 

Syntax: Clear; 

Clears the active window and moves the turtle to the Home position. 
Forwd 

Syntax: Forwd(Dist); 

Moves the turtle forward by the distance given by the integer expression Dist. 
The turtle moves from its current position in the direction that it faces and draws 
a line in the current pen color. If Dist is negative, the turtle moves backwards. 

Heading 

Syntax: Heading; 

Returns an integer in the range 0..359 that gives the direction in which the 
turtle is currently pointing. 0 is upwards, and increasing angles represent head- 
ings in a clockwise direction. 

Home 

Syntax: Home; 

Puts the turtle at its Home position (coordinates 0,0, the middle of the active 
window) and points it in heading 0 (upwards). 
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NoWrap 

Syntax: Nowrap; 

Disables the turtle from '^wrapping'*; that is, reappearing at the opposite side 
of the active window if it is moved past the window boundary. NoWrap is the 
system's initial value. 

PenDown 
Syntax: PenDown; 

Sets the "pen** to the screen so that the turde draws a line as it moves. This is 
the initial status of the pen. 

PenUp 

Syntax: PenUp; 

Lifts the pen so the turtle moves without drawing a line. 

SetHeading 

Syntax: SetHeading(Angle); 

Turns the turtle to the angle specified by the integer expression Angle, 0 is 
upwards, and increasing angles represent clockwise rotation. If Angle is not in 
the range 0..359, it is converted into a number in that range. 

Four integer constants are predefined to turn the turtle in the four main direc- 
tions: North = 0 (up), East = 90 (right), South = 180 (down), and West = 270 
(left). 

SetPosition 

Syntax: SetPosition(X,Y); 

Moves the turtle, without drawing a line, to the location with the coordinates 
given by the integer expressions X and Y. 

TurnLeft 

Syntax: TurnLeft(Angle); 

Turns the turtle Angle degrees from its current direction. Positive angles turn 
the turtle to the left; negative angles turn it to the right. 
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TurnRight 

Syntax: TurriRight( Angle); 

Turns the turtle Angle degrees from its current direction. Positive angles turn 
the turtle to the right; negative angles turn it to the left. 

When the window is set, the turtle is initialized to its Home position and 
heading north (or 0 degrees). 

TurtleDelay 

Syntax: TurtleDelay(Ms); 

Sets a delay in milliseconds between each step of the turtle. Normally, there is 
no delay. 

Wrap 

Syntax: Wrap; 

Makes the turtle reappear at the opposite side of the active window when the 
turde exceeds the window boundary. Use NoWrap to return to normal. 

Xcor 

Syntax: Xcor; 

Returns the integer value of the turtle's current X coordinate. 
Ycor 

Syntax: Ycor; 

Returns the integer value of the turtle's current Y coordinate. 
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Mac versus IBM Turtlegraphics 



There are some diflFerences between Mac Turtlegraphics and IBM Tur- 
tlegraphics. The Home position (0,0) in Mac turtle graphics is the upper left- 
hand corner of the window. In IBM turtle graphics, the home position (0,0)is the 
center of the window. The ClearScreen procedure is called Char. The following 
procedures are not supported: 

• HideTurtle 

• ShowTurtle 

• TurtleWindow 

• TurtleThere 

• SetPenColor 

The turtle itself is not supported, only its actions. 



An Example 



Type in the following program. It draws a circle using the TurnRight and Forwd 
procedures. 

prograi TurtleDraw; 

uses MemTypes , Quickdraw , OSIntf , Toollntf , Turtle ; 
var 

fingle : Integer; 
begin 

PenDown; { start drawing > 

for Angle := D to fl9 do { for loop to draw circle > 
begin 

TurnRight(4) ; { turn right n degrees > 

Forwd (5); { draw 5 pixel line segment > 

end; 

ReadLn; {wait for carriage return } 

end. { end of TurtleDraw > 
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Glossary 



active window: The front-most window on the desktop; the window where the 
next action specified will take place. The title bar of the active window is high- 
hghted. 

Alarm Clock: A desk accessory that displays the current date and time. 

Apple menu: The menu on the far left in the menu bar, indicated by an apple 
symbol. 

ASCII: American Standard Code for Information Interchange. ASCII is a stan- 
dard code for representing characters (letters, numbers, and symbols) as binary 
numbers. 

benchmark: A point of reference used to measure the performance of hardware 
and/or software. 

bitmap: A grid of bits that makes up your Macintosh screen. 

buttons: The squares in dialog boxes that you click on to assign, confirm, or 
cancel an action. See also mouse button. 

cancel button: A button that appears in dialog boxes. Clicking this button cancels 
the command. 

check box: The small box or circle associated with an option in a dialog box that, 
when clicked on, adds or removes the option. 

click: To position the pointer on something, then press and release the mouse 
button. 



447 



Clipboard: The file that holds what you last cut or copied. 

close: To put away a window and call up the icon that represents it. 

Close box: The small blank box on the far left side of the title bar of an active 
window. Clicking on the Close box puts away the window. 

Q (command key): A key that, when held down while another key is pressed or 
a mouse action is performed, causes the corresponding command to take eflFect. 

compiler: A program that takes high-level instructions (source code) and converts 
them into machine code that the computer can read. 

Control Panel: A desk accessory that lets you change the speaker volume, start 
the AppleTalk connection, create a RAM cache, and set other preferences. 

cut: To remove something by selecting it and choosing Cut from the Edit menu. 
What you cut is placed, into the Clipboard file. 

data fork The part of a file with information that is retrieved via the File Man- 
ager. 

declare: State a variable's attributes. 

desk accessories: Small applications that are available on the desktop from the 
Apple menu regardless of which application you're using. Turbo Pascal lets you 
create your own desk accessories. 

desktop: The Macintosh working environment: the menu bar and the gray area 
on the screen. 

dialog box: A box that contains a message and requests information from you. 
Sometimes the message is a warning that you're asking your Macintosh Plus to 
do something it can't do or that you're about to destroy some of your information. 
In these cases the message is often accompanied by a beep. 

double-click: To position the pointer where you want an action to take place, then 
press and release the mouse button twice (without moving the mouse). 

drag: To position the pointer on something, press and hold the mouse button, 
move the mouse to a new position, and release the mouse button. This action is 
used to select several items at once, or to move a file into another file or to a 
different location on the screen. 

folder: A file containing documents, applications, or other folders on the des- 
ktop. Folders allow you to organize information under specific headings. 

font: A complete set of characters in one typeface. Common fonts include Cou- 
rier, Helvetica, and Times. Each font family can come in different weights and 
styles, such as bold and italic. 
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heap: A portion of memory used by Turbo Pascal (and other compilers) to store 
pointer variables during program execution. A heap's memory is organized like a 
stack; that is, from the bottom up. 

Hierarchical File System (HFS): A method of using folders to organize docu- 
ments, applications, and other folders on a disk to keep together related informa- 
tion. Folders (analogous to subdirectories in DOS systems) can be nested inside 
other folders to create as many levels hierarchy as you need. Opening a folder 
displays only the information you Ve put in that folder. 

I-beam cursor: A type of pointer used to enter and edit text. 

icon: A graphic representation of an object, a concept, or a message. Following 
are the Turbo Pascal and Mac icons. 



Turbo Pascal compiler icon 

Icon for Turbo Pascal program compiled to disk 

Turbo Pascal source file icon 

Program compile-time error icon 

Run-time error icon 
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A 



D). 



^ FONT/DA MOVER icon 

RMAKER (resource compiler) icon 
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UNITMOVER icon 
Compiled desk-accessory icon 
Compiled unit icon 
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initialize: To prepare a disk to receive information. 

I/O: Input/output. To enter information into a computer is to input; to move the 
information out (usually to a printer or a plotter) is to output. 

JSR: Jump to Subroutine. 

machine code: Instructions to the computer in binary code (that is, Os and Is); 
also known as assembly language. A compiler, like Turbo Pascal, takes your high- 
level instructions and translates them into machine code. 

MDS: Macintosh Development System. 

menu: A list of commands that appears when you point to and press the menu 
title in the menu bar. Dragging through the menu and releasing the mouse but- 
ton while a specific command is highlighted causes that command to be imple- 
mented. 

menu bar: The horizontal strip at the top of the screen that contains the menu 
titles. 

menu title: A word, phrase, or symbol in the menu bar that designates a menu. 
Clicking on the menu title causes the title to be highlighted and its menu to 
appear below it. 

mouse: A small device, attached to your computer, that you roll around on a flat 
surface. The pointer or cursor on the screen echoes the movements of the 
mouse. 

mouse button: The button on the top of the mouse. Generally, pressing and 
releasing the mouse button initiates some action on whatever the pointer is on, 
and releasing the button confirms the action. 

Option key: A key (like the Shift key) that gives an alternate meaning to the key 
you press while keeping the Option key pressed down. You use it to type foreign 
characters or special symbols. 

package: A set of data structures and routines stored as resources in the SYS- 
TEM file and brought into memory only as needed. 

pointer cursor: A small shape on the screen, most often an arrow pointing up 
and to the left, that echoes the movement of the mouse. 

queue: Line. 

resource: A piece of information, stored in a resource file, that can be accessed 
by its type and ID. 

resource fork The part of a file with information used by an application, as well 
as the application code itself 

run-time error: An error that occurs while a program is executing. 
SANE: Standard Apple Numeric Environment library. 
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scroD: To move a document or directory in its window so that you can see a 
diflFerent part of it. You can also scroll the directory in some dialog hoxes. 

scroll arrow: An arrow on either end of a scroll bar. Clicking a scroll arrow moves 
the document or directory one Une. Keeping the mouse button pressed on the 
scroll arrow scrolls the document continuously. 

SCSI: Small Computer System Interface, an industry-standard interface for con- 
necting computers with peripheral devices (hard disks, printers, and so on). The 
Macintosh Plus includes an SCSI port. 

select: To designate where the next action will take place. To select, you click or 
drag across information. 

shift-click: A technique that allows you to extend or shorten a selection by hold- 
ing down the Shift key while you select (or de-select) something related to the 
current selection, syntax: The rules of a programming language that specify how 
the language symbols can be put together to form meaningful statements. If a 
program violates the language syntax rules, a syntax error occurs. 

title bar: The horizontal bar at the top of a window that shows the name of the 
window's contents and lets you move the window. 

two's-complement arithmetic: A way of representing negative and positive inte- 
gers, where an integer is negative if its high bit is set. 

window: The area that displays information on the desktop. You can open or 
close a window, move it around on the desktop, and sometimes change its size, 
edit its contents, and scroll through it. 
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A 

''About...'* box, 88-89 
Activate events, 94 
ALRT resource, 143 
Apple menu, 179-180 

About Turbo... command, 179 

desk accessories, 89-90, 180 
Appletalk, 8, 64, 429-432 
Application globals, 325-326 
Application heap, 325-327 
Application parameters, 325-326 
Applications, writing 

activate events, 94-95 

basic structure, 81, 82 

cleaning up, 101 

clicking windows, 90 

data structures, 96 

demo programs, 79 

event handling, 83-84 

initialization, 99-101 

keyboard events, 92-93 

miscellaneous events, 95 

mouse events, 85 

menu commands, 86-90 

organization, 82 

programming style, 81 

sample programs, 8, 79-80 

segmentation, 101-102 

update events, 93-94 
Arithmetic functions 

Abs, 291 

ArcTan, 292 

Cos, 292 

Exp, 292 

Expl, 318 

Exp2, 318 

Int, 291 

Ln, 292 

Lni, 318 

Log2, 318 

Sin, 291 

Sqr, 291 

Sqrt, 291 

Tan, 319 

Xpwrl 318 

XpwrY, 318 
Arithmetic functions (SANE) 

CopySign, 317 

LogB, 317 

NextDouble, 317 

NextExtended, 317 

NextReal, 317 



Remainder, 316 

Rint, 317 

Scalb, 317 
Array qualifiers, 227-228 
Array-types, 216-217, 329-^30 
Assembly language. See also Machine 
code 

Assembly language, linking 

operations on relocatable symbols, 335 

procedures and functions, 334 

register saving devices, 336 

variables, 335 
Assembly-language routines 

external, 65-66 

inline, 66-67 
@ operator, 241-242 
Auto-indenting, 20 

B 

Back up. See Distribution disks, to copy 
Blocks, 205-208 

predefined identifiers, 208 

rules of scope, 207 

syntax, 206-207 
BNDL resource, 143 
Boolean-types, 212, 328 
Bundle bit, 98 

C 

Calling conventions, 331-333 

entry and exit code, 333 

function results, 332-333 

value parameters, 332 

variable parameters, 331 
case statemient, 249-250 
Change command, 189 
Char-types, 212, 328 
Character size command, 191 
Character strings, 202 
Check marks, 88 
Check Syntax command, 193 
Cleaning up, 101 
Clear command, 186 
Clicking. See Mouse operations; 

Applications, clicking windows 
Close box, 90-91 
Comments, 203 
Comparing Pascals, 341-349 

ANS Pascal, 341^6 

Lisa Pascal, 346-349 
Compile To Disk command, 193 
Compile To Memory command, 192 
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Compiler, 29-31. See also Compile menu 
Compiler directives, 40-46, 361-366 
include files, 45 

input/output error checking, 41--43, 
163 

output (code) files, 46 

range checking, 43-44, 164 
Compile menu, 27-35, 192^194 

Check Syntax command, 193 

Find Error command, 193 

Get Info command, 34, 193 
Get Info box, 193 

Options command, 34-35, 194 

Run command, 12, 28-29, 192 

To Disk command, 13, 192 
code files produced, 30-31 
to specify file names, 31 

To Memory command, 31, 192 
Compiling Options command, 194 
Compiling to RAM, advantages and 

disadvantages, 30-31 

Errors during compilation, 28 
Compiling units. See Units, compiling 
Concat procedure, 293 
Console handling procedures and 

functions, 294-296 

ClearEOL, 295 

Clearscreen, 294 

DeleteLine, 295 

GotoXY, 295 

InsertLine, 295 

KeyPressed, 295 

ReadChar, 295-296 
const statement 

example of, 15 

setting Step, 15 
Constant declarations, 203 
Constants, 311 

Conversion procedures and fimctions, 
313-316 
Copy command, 185 
Copy procedure, 294 
CURS resource, 144 
Cursors, 19 

finding a lost bar cursor, 24 

Home cursor command, 189 
Customizing Turbo Pascal, 9 
Cut command, 185 
Cut-and-paste. See Files, to cut and 
paste 



D 

Data fork, 138 

Data structures, 96, 110-114 

Debugging 

compiler errors, 161-162 

input/output error checking, 163 

MACSBUG, 8, 166-175 
commands, 169-175 
"trap'' calls, 172, 173-175 

range checking, 164 

run-time errors, 162-163 

SysError, 164^165 

trace statements, 165 

See also Errors 
Delete, 294 

Denormalized numbers, 307 
Desk accessories, compiling, 127 

moving out of system files, 128 
Desk accessories, writing 

basic structure, 107-110, 130 

closing, 126-127 

compiling, 127 

data structures 

device control entry, 111-113 
driver header, 110-111 
global variables, 114 

event handling, 120-124 

initialization, 114-120 

installing, 127-129 

menu handling, 125 

sample (MYDA), 127-129, 130 

support routines, 125-126 
Desktop 

to bypass, 7 
Device definitions, 336-339 

device input/output functions, 337 
examples of, 338^39 

device procedure, 336 
Distribution disks 

files on, 7-9 

to copy, 5-7 

on one disk drive, 6 
on a hard disk, 7 
DITL resource, 144 
DLOG resource, 145 
Divide-by-zero exception, 310 
Drag bar, 92 

Dynamic allocation, 288-289 
Dispose procedure, 288 
MaxAvail function, 289 
MemAvail function, 289 
New procedure, 288 
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E 

Edit menu, 18, 185-187 

Clear command, 22, 186 

Copy command, 22, 185 

Cut command, 185 

Options command, 186-187 
Options dialog box, 186 

Paste command, 22, 186 

Shift Left command, 186 

Shift Right command, 186 

Undo command, 22, 23, 185 
Edit Transfer command, 183 
Editing, number of windows, 30 
Editing Options command, 186 
Enumerated-types, 212-213, 328 
Environmental access procedures and 

functions (SANE), 321-324 
Erase. See Files, to delete text 
Error messages, 351-357 

compiler errors, 351-356 

system errors, 357 
Errors 

compiler, 161-162 

run-time (system), 28, 32-33 

syntax, 12, 31-32 

See also Debugging, 
Event handling, 83-95 
Exception conditions constants, 311 
Execute a program, 13 
Exit 

Exit procedure, 287 
See also File menu, Quit command; 
Halt procedure 
Expressions, 231-243 
function calls, 242-243 
operators, 235-238 

arithmetic, 235-237 

@, 241-242 

logical, 237 

relational, 239 

comparing packed strings, 240 
comparing pointers, 240 
comparing sets, 240 
comparing simple types, 239 
comparing strings, 240 
testing set membership, 240 
set, 238 
string, 238 

rules of precedence, 231 

set constructors, 243 

syntax, 232-235 



value-type-casts, 244 
external procedure declaration, 259-260 

F 

File menu, 180-184 

Close command, 25, 181 

Edit Transfer command, 183 
Edit Transfer dialog box, 183 

New command, 19, 180 

Open command, 181 

Open selection command, 181 

Page Setup command, 182 
Page Setup dialog box, 182 

Print command, 183 

Quit command, 13, 184 

Save command, 25, 181 

Save As command, 25, 182 

Save Defaults command, 184 

Transfer command, 184 
File-save dialog box. See Save-file dialog 

box 
Files 

to add text, 21 

to copy text, 22 

to cut and paste, 21-22 

to delete text, 12, 21 

to edit, 18-21 

to enter, 12^15, 19-20, 38 

to replace text, 22 

to save, 25 

to undo changes, 22, 23 

See also Edit menu; File menu; 

Formatting text 
File-types, 220, 330-331 
FillChar procedure, 297 
Financial functions (SANE) 

Annuity, 319 

Compound, 319 
Find command, 188 
Find Error command, 193 
Find Next command, 188 
FINDER, 8 
FixMath, 63, 425-426 
FONT/DA MOVER, 8 

to install desk accessories, 157-159 

to launch, 155-157 
Font Menu, 191 
for statement, 252-253 
Format menu, 190-191 

Character point sizes, 191 

Stack Windows command, 190 

Tile Windows command, 190 



456 



Turbo Pascal for the Macintosh 



Zoom Window command, 191 
Formatting disks. See Initializing disks 
Formatting text, 23-24 
forward procedure declaration, 259 
FREF resource, 145 
Function calls, 242 
Function declarations, 260-262 
Functions 
SANE 

CopySign, 317 

GetPrecision, 322 

GetRound, 321 

LogB, 317 

NextDouble, 317 

NextExtendedy 317 

NextReal 317 

Num2Extended, 314 

Num2Integer, 313-314 

Num2LongInt, 313-314 

Remainder, 316 

Rinf , 317 

Scalh, 317 

Str2Num, 315-316 

TestHalt, 322 

TextException, 322 
Standard 

Afes, 291 

Annuity, 319 

ArcTan, 292 

C/in 289 

ClassComp, 320 

ClassDouble, 320 

ClassExtended, 320 

ClassReal, 320 

Compound, 319 

Concat, 293 

Copt/, 294 

Copy Sign, 317 

Co5, 292 

E:rp, 292 

Expl, 318 

Exp2, 318 

F/oaf , 290 

GetPrecision, 322 

GetRound, 321 

Hi, 297 

//Wore/, 298 

Znf, 291 

KeyPressed, 295 
Length, 293 
Ln, 292 



Lni, 318 

Lo, 298 

Logi>, 317 

Log2, 318 

LoWord, 298 

MflxAuaiZ, 289 

MemAvail, 289 

NaN, 321 

NextDouble, 317 

NextExtended, 317 

NextReal, 317 

Num2Extended, 314 

Num2Integer, 313 

Num2Longlnt, 313 

Ocici, 293 

Orff, 289 

Orci4, 289 

Poinfer, 290 

Fr^d, 293 

RandomX, 321 

ReadChar, 295 

Relation, 321 

Remainder, 316 

Rmf, 317 

Rowncf, 290 

ScflZ^?, 317 

ScanEQ, 297 

ScanNE, 297 

SignNum, 320 

Sin, 291 

Siz^O/, 296 

S(/r, 291 

Sf/rt, 291 

Str2Num, 315 

Sttcc, 292 

S«;ap, 298 

SujapWbrci, 298 

Tan, 319 

TestHalt, 322 

TextException, 322 

Trwnc, 290 

Xpiorl, 318 

XpM;rY, 318 
Standard (text files) 

EOF, 282 

Eo/n, 282 

S^ej^Eo/, 282 

SeekEoln, 282 
Standard (typed-files) 

FifeFos, 277 

FileSize, 277 
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G 



L 



Get Info command, 34, 193 
goto statement, 247 
Gra/3D, 63, 427-428 
Grow box, 91-92 

H 

Halt procedure, 288 
Halt settings, 310 
Handles, 96 
Hi function, 297 
Hierarchical File System, 34 
HiWord function, 298 
Home Cursor command, 190 

I 

ICON resource, 146 

Icons, 447 

ICN resource, 146 

Identifiers, 199, 208 

if statement, 248 

IMAGEWRITER, 8 

Indexes, 227-228 

Inexact exception, 310 

Initialization, 99-100 

Initializing disks, 6 

inline codes and traps, 66 

inline procedure declaration, 260 

Inquiry functions (SANE) 

ClassComp, 320 

ClassDouble, 320 

ClassExtended, 320 

ChssReal, 320 

SignNum, 320 
Insert procedure, 294 
Inside Macintosh, 16 
Integer-types, 211, 327-328 
Interface units. See Units, interface 
Interrupt switch (Mac Plus), 28 
Invalid operation exception, 309 
lOResult codes, 358 

J 

Jump table, 325-326 
K 

Keyboard events, 92 
Keys, special, 21 



Labels, 200 

Length procedure, 293 

Line length, maximum, 203 

Linking with assembly language, 

334-336. See also Assembly 

language, linking 
La function, 298 
Loading Turbo Pascal, 11 
Longint, 328 
Longlnt-types, 211-212 
LoWord function, 298 

M 

Machine code, 28-30. See also 

Assembly-language routines 
MACINTALK, 8 
Macintosh 

architecture, 325-327 

bit-mapped graphics, 49-50 

event-driven software, 49, 51-52 

graphics-only display, 48 

internal data formats, 327-331 

philosophy behind, 47-55 

system sofhvare, 49 
Memory Manager, 327 
Toolbox and operating system 

routines, 52-55 

user interface, 48, 50-51 
Macintosh character set, 435-440 
Macintosh interface units. See Units, 

interface 
MacPtint, 63, 419-424 
MACSBUG, 165-168 
Managers. See Macintosh, system 

software 
MBAR resource, 147 
MemAvail function, 289 
Memory Manager, 327 
MemTypes, 62, 373 
Menu bar, Turbo Pascal, 178-179 
Menu commands 

selecting, 177-178 

writing, 85 
Menu resource, 147 
Mouse events, 85-89 
Mouse operations 

clicking, 17 

double-clicking, 17 

shif^-clicking, 17 
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MoveLeft procedure, 296 
MoveRight procedure, 296 
Multiple calls to open, 119 
MYDA. See Desk accessories, writing 

N 

NaN codes, 307, 359 
NaN fiinction (SANE), 321 
New command, 180 
Numbers, 200-202 

O 

Open command, 181 
Open Selection command, 181 
Opening Turbo Pascal, 18 
Operating system routines, 52-55 
Operators, 235-242 
arithmetic, 235-237 
@, 241-242 
logical, 237 
relational, 239 
comparing packed strings, 240 
comparing pointers, 240 
comparing sets, 240 
comparing simple types, 239 
comparing strings, 240 
testing set membership, 240 
Options command, 34^-35 
Ordinal functions, 292-293 
Odd, 293 
Pred, 293 
Swcc, 293 
Ordinal-types, 210-211 
OSIntf, 62, 381-398 
Overflow exception, 310 

P 

Packages. See Macintosh, system 

software 
Packlntf, 63, 41^18 
Page Setup command, 182 
Parameters, 262-264 

untyped variable, 264 

value, 263-264 

variable, 264 
PasConsole, 60, 369 
PasInOut, 60, 368 
PasPrinter, 61, 370 
PasSystem, 60 
Paste command, 186 
PAT resource, 186 



PAT# resource, 148 
POS procedure, 293 
Pointer-types, 220-221, 329 
Pointers, 96 
Print command, 183 
PROC resource, 149 
Procedures 
FillChar, 295 
MoveLeft, 296 
MoveRight, 296 
SANE 

GetEnvironmenty 323 

Num2Str, 314-315 

ProcEntry, 323 

ProcExit, 324 

SetEnvironmenty 323 

SetException, 309, 322 

SetHalt, 323 

SetPrecision, 322 

SetRound, 322 

TestException, 309, 322 
Standard (all files) 

ClearEOL, 294 

ClearScreen, 294 

Close, 275 

Delete, 294 

DeleteLine, 295 

Dispose, 288 

Erase, 276 

Exit, 287 

GotoXY, 295 

Halt, 288 

Insert, 294 

InsertLine, 295 

lOResult, 276 

New, 288 

Rename, 275 

Reset, 274 

Rewrite, 275 
Standard (text files) 

Read, 278 

ReadLn, 279 

Wnte, 280 

WnteLn, 281 
Standard (typed-files) 

Eof, 277 

Read, 276 

Seek, 277 

Write, 276 
Turtle graphics 

Back, 442 

Cfear, 442 
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Forwd, 442 

Heading 442 

Home, 442 

NoWrap, 443 

PenDown, 443 

PenUp, 443 

SetHeading, 443 

SetPositioUy 443 

TurnLeft, 443 

TurnRight, 444 

TurtleDelayy 444 

Wrap, 444 

Xcor, 444 

Ycor, 444 
Procedure declarations, 257-260 
external, 259-260 
forward, 259 
inline, 260 
Program lines, 203 

Programming. See Applications, writing; 
Files, to enter 

Q 

QuickDraw, 62, 374-380 

sample routines, 14 
Quit command, 184 

R 

RandomX function (SANE), 321 
ReadLn statement, function of, 12 
Real-types, 214, 328 
Record-types, 217-219, 330 
Records and field designators, 228 
Relation function (SANE), 321 
repeat statement, 250-251 
Reserved words, 198 
Resource files, 97-99, 103. See also 

RMAKER 
Resource fork, 128 
Resource IDs, 117-118 
Resource specifications, 142-150 
Resource types, 142-150 
Resources 

defining, 150 

editing, 103 
RMAKER, 8, 80 

creating resource files, 138-140 

defining resources, 140-142, 150-152 

using resource files, 138, 154 

using RMAKER, 153 
Rules of scope, 207-208 
Run command, 12, 28-29, 192 



Run-time environment, 40 
Run-time errors, 28, 32-^, 357 

S 

Sample Pascal programs, 39 
SANE, 61, 299, 371-372 
SANE arithmetic functions. See 
Arithmetic functions (SANE) 
SANE data types, 300-304 

choosing, 300-301 

formats, 302-^04 
comp, 303 
double, 303 
extended, 303-304 
single, 302-303 

range and precision, 302 

values represented, 301 
SANE engine, 304-310 

extended arithmetic, 304-305 

infinities, 306 

NaNs, 306-307 

number classes, 305-306 
SANE environment, 307-310 

exception flags, 309 

SetException procedure, 309 
TestException procedure, 309 

halt settings, 310 

rounding direction, 308 

rounding precision, 309 
SANE library, 310-324 

DecForm type, 311 

DecStr type, 311 

DecStrLen constant, 311 

Environment type, 313 

exception condition constants, 311 

Exception type, 312 

NumClass type, 312 

Num2Extended function, 314 

Num2Integer function, 313-314 

Num2LongInt function, 313-^14 

Num2Str procedure, 314-315 

RelOp type, 312 

RoundDir type, 313 

RoundPre type, 313 

Str2Num function, 315-316 
Save, 25, 137 
Save command, 181-182 
Save As command, 182 
Save Defaults command, 184 
Save-file dialog box, 12, 25 
ScanEQ function, 297 
ScanNE function, 297 



460 



Turbo Pascal for the Macintosh 



SCSIIntf, 65, 434 
Search and replace dialog box, 24 
Search menu, 24-25, 187-190 
Change command, 25, 189 
Change dialog box, 189 
Verification dialog box, 189 
Find command, 24, 188 
Find dialog box, 188 
Find Next command, 25, 188 
Home Cursor command, 189 
Window command, 30, 190 
Segmenting large programs, 101 
Selecting text, 21-22 
Set constructors, 243 
Set-types, 220, 329 
Shift Left command, 186 
Shift Right command, 186 
Simple-types, 210-214 
StoO/function, 296 
68000 microprocessor, 29 
Speechlntf, 64, 433 
Stack Windows command, 190 
Standard Pascal 

run-time environment, 40 
sample programs, 39 
Statements, 245-255 
simple, 245-247 
assignment, 246 
goto, 247 
procedure, 246 
structured, 247-255 
compound, 247-248 
conditional, 248 
case, 249-250 
if, 248 
repetitive, 250-253 
for, 252-253 
repeat, 250-251 
while, 251 
with, 254-255 
STR resource, 149 
STR# resource, 149 

String procedures and functions, 293-294 

Concat, 293 

Copy, 294 

Delete, 294 

Insert, 294 

Length, 293 

Pos, 293 
String qualifiers, 227-228 
String-types, 215, 329 
Structured-types, 215-220 



Subrange-types, 213 
Swap function, 298 
SwapWord function, 298 
Syntax, 206 

Syntax error. See Error, syntax 

SYSTEM, 8 

SYSTEM FOLDER, 8 

System (run-time) errors, 28, 32-33, 357 

System software, 49, 52-55, 327 

T 

Tile Windows command, 191 
Tokens, 197-203 

reserved words, 198 

special symbols, 197-198 
Toolbox routines, 52--55 
Toollntf, 62, 399-413 
Transfer command, 184 
Transfer functions, 289-290 

Chr, 289 

Float, 290 

Ord, 289 

Ord4, 290 

Pointer, 290 

Round, 290 

Trunc, 290 
Transfer menu, 194-196 

meta-characters, 195 
traps, 66 
TURBO, 8 

Turbo Pascal extensions, 343-345 
Turbo Pascal menu bar, 178-179 
Turtle graphics, 441-445 
Types, 209-224, 3U 

identity and compatibiHty, 221-223 
pointer types, 220-221 
simple-types, 210 

ordinal-types, 210-21L 
boolean-type, 212 
char-type, 212 
enumerated- type, 212-213 
integer-type, 211 
longint-type, 211-212 
subrange-type, 213 
real-type, 214 
string-types, 215 
structured- types, 215-220 
array-types, 216-217 
file-types, 220 
record-types, 217-219 
set- types, 220 
type-declaration part, 224 
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Underflow exception, 309 
Undo command, 23, 185 
UNITMOVER, 8, 77, 133^136 

deleting units, 136 
Units 

compiling, 73 

definition of, 57-58, 69 

for segmentation, 75-77 

run-time environment units, 40 

structure of, 69-72 
implementation, 71-72 
initialization, 72 
interface, 71 

use of, 59, 73-74 

writing 

Units, Mac interface, 367-434 

AppkTalk, 429^32 

FixMath, 425-426 

GraftD, 427-428 

MacPrint, 419-424 

MemTypes, 373 

OSIntf, 381-398 

Packlntf, 414-418 

PasConsole, 60, 369 

PasInOut, 60, 368 

PasPnnter, 61, 370 

QuickDraw, 374-380 

SANE, 371-372 

SCSIIntf, 434 

Speechlntf, 433 

Toollntl 399-413 
Units, Turbo Pascal standard 

Mac interface, 61-65 

run-time support, 60-61 
Untyped variable parameters, 264 
Update events, 93 



Variable parameters, 264 
Variables, 14, 225-229 

declarations, 225-226 

qualifiers, 226-229 

arrays, strings, and indexes, 

227- 228 

pointers and dynamic variables, 

228- 229 

records and field designators, 228 

references, 226 

type casts, 229 
Value parameters, 263-264 
Value-type-casts, 244 



while statement, 251 

WIND resource, 150 

Window command, 190 

Windows, Turbo Pascal, 30. See also 

Search menu, Windows command 
with statement, 254-255 
Write statement, 14 
Writing applications. See Applications, 

writing 

Writing programs. See Files, to enter 
Z 

Zoom Window command, 191 
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Turbo Pascal for the Macintosh 



Borland 
Software 




INTERNATIONAL 4585 Scotts Valley Drive, Scotts Valley, CA 95066 



Available at better dealers nationwide. 

To order by credit card, call (800) 255-8008; GA (800) 742-1133. 



Whether you're running WordStar,® Lotus,® dBASE® 
or any other program, SideKick puts all these desktop 
accessories at your fingertips— Instantly! 

A full-screen WerdStaNIke Editor to jot 

down notes and edit files up to 25 pages 
long. 



A Monthfy Calendar iroin 1901 through 
2099. 



A Phone Directory for names, addresses, 
and telephone numbers. Finding a name or a 
number is a snap. 

An Autodialer for all your phone calls. It will 
look up and dial telephone numbers for you. 
(A modem is required to use this function.) 
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Appointment Calendar to remind you 
of important meetings and appointments. 

A full-featured Calculator Ideal for 
business use. It also performs decimal 
to hexadecimal to binary conversions. 

An ASCII Table for easy reference. 




All the SideKick windows stacked up over Lotus 1-2-3.* 
From bottom to top: SideKick's "Menu Window." ASCII 
Table, Notepad, Calculator, Appointment Calendar, Monthly 
Calendar, and Phone Dialer. 



Here's SideKick running over Lotus 1-2-3. In the 
SideKick Notepad you'll notice data that's been imported 
directly from the Lotus screen. In the upper right you can 
see the Calculator. 



The Critics' Choice 



"SideKick is by far the best we've seen. It is also 
the least expensive." 

—Ron Mansfield, ENTREPRENEUR 

"If you use a PC, get SideKick. You'll soon become 

dependent on it." , _ „ „™ 
^ —Jerry Pournelle, BYTE 



"In a simple, beautiful implementation of WordStar's 
block copy commands, SideKick can transport all . 
or any part of the display screen (even an area 
overlaid by the notepad display) to the notepad." 

—Charles Petzold, PC MAGAZINE 

"SideKick deserves a place in every PC." 

—Gary Ray, PC WEEK 

Suggested Retail Price: $84.95 (not copy protected} 

system configuration: IBM PC, XT, AT^ PCjr and true compatibies. The IBiM PCjr will only accept the SideKicic not copy- 
versions. PC-DOS (MS-DOS) 2.0 or greater. 128K RAM. One disk drive. A Hayes-compatibie modem, IBM PCjr internal 
or AT&T Modem 4000 is required for the autodialer function. 

SideKick is a registered trademark of Borland .International, Inc. dBASE is a registered tradennark of 
Ashton-Tate. IBM, XT, AT, and PCjr are registered trademarks of International Business Machines Corp. 
AT&T is a registered trademark of American Telephone & Telegraph Company. Lotus and 1-2-3 are 
E R N A T I 0 N A L registered trademarks Of Lotus Development Corp. WordStar Is a registered trademark Of MicroPro 
International Corp. Hayes is a trademark of Hayes Microcomputef Products, inc. bor ooeoB 




for the Mac 



SideKick for ttie Mac brings information 
management, deslctop organization, and 
teiecommunications to your MacintostiT 
Instantiy, wliile running any ottier program! 



A full-screen editorlmini-word processor 

lets you jot down notes and create or edit 
files. Your files can also be used by your 
favorite word processing program, like 
MacWrite" or Microsoft* Word. 

A complete telecommunications program 

sends or receives information from any 
on-line network or electronic bulletin 
board while using any of your favorite 
application programs (modem required). 

A full'leatureil financial and scientific 
calculator sends a paper-tape output to 
your screen or printer and comes 
complete with function keys for financial 
modeling purposes. 

A print spooler prints any "text only" file 
while you run other programs. 

A versatile calendar lets you view your 
appointments for a day, a week, or an 
entire month. You can easily print out your 
schedule for quick reference. 

A convenient "Tliings-tO'Do" file reminds 
you of important tasks. 



A convenient alarm system alerts you to 

daily engagements. 

PhoneLinir allows you to autodial any 
phone number, as well as access any long- 
distance carrier. 

A phone log keeps a complete record of 
all your telephone activities. It even 
computes the cost of every call. 

Area code look-up provides instant access 
to the state, region, and time zone for all 
area codes. 

An expense account file records your 
business and travel expenses. 

A credit card file keeps track of your 
credit card balances and credit limits. 

A report generator prints out your mailing 
list labels, phone directory, and weekly 
calendar in convenient sizes. 

A convenient analog clock with a sweeping 
second-hand can be displayed anywhere 
on your screen. 

On-line fielp is available for all of the 
powerful SideKick features. 



Best of all, everything runs concurrently 



Suggested Retail Price: $99.95 (not copy protected) 



Miiiimiiiii system configuration: 128K RAM and ono disit drive. IWo disic drives are recommended if you wish to use otiier 




SideKick is a registered trademark and PhoneLink is a trademark of Borland International, Inc. 
Macintosh is a trademark of Mcintosh Laboratory, Inc. licensed to Apple Computer, Inc. 
MacWrite is a trademark of Apple Computer. Inc. Microsoft Word is a registered trademark of 
Microsoft Corp. 



The Organizer For The ComputerAge! 

Traveling SideKick \s BMerWare^ a binder you talce with you when you travel 
and a software program— which includes a Report Generator— that generates ^nA 
prints out all the information you'll need to take with you. 



Information like your phone Jist, your client list 
your address book, your calendar, and your 
appointments. The appointment or calendar files 
you're already using in your SMeKick* can auto- 
matically be used by your Traveling SideKick. You 
don't waste time and effort reentering Informatton 
that's already there. 

One keystroke prints out a form fike your address 
book. No need to change printer paper; 



you simply punch three holes, fold and clip 
the form into your Traveling SkleKk:k binder, and 
you're on your way. Because Traveling SMeKtek Is 
CAD (Computer-Age Designed), you don't fool 
around with low-tech tools like scissors, tape, or 
staples. And because Traveling SideKick is 
electronic, it works this year, next year, and all the 
"next years" after that Old-fashtoned daytime 
organizers are history in 365 days. 



What's inside Tmeling SidMcic 




W POCKET ON a*iCK aAP, fOft U« W AW Of THE 

oflQANtaBRsecnONS. 



pfiEPfwnEDAor 



SLACK P6N THAT FITS IN RAP FOR EAST ACCESS. 



CONIAINS MAPS THAT SHOW AREA CODES AND 
TIME ZONES. TOLL-PHEE NUMBERS FOR TRAVEL 
ACCOMOCiAnONS. MEtmC CONVCTSION CHARTS. 



TLOQANO 
MFORMAtlON. 



YEARLY; MONTHLY, WEBCLY. AND DAILY 
ENGAGGMENT CALENDARS SUmEMENT THOSE 
YOU PRINT OUT VWffl TRAVELING SIDEKKX 



"CALCUtATOR ' 

IN ONE OF TWO BUSWESS-CARO-SIZE STORAGE 

POCa<ETa ' 



^VaJfO SIOEKtCK SOFTWARe 

GENERATES. UPDATES. WD PRINTS YOUR 
ADDRESS AND CALENDAR FILES. 



^Suggested Retell Price: $69.95 



Wliai tlie software program and its 
Heport Generator do for you before 
you go— and wfien you get bacic 

Before you go: 

• Prints out your calendar, 
appointments, addresses, phone 
directory, and whatever other 
Information you need from your 
data files 

Wben you return: 

• Lets you quickly and easily enter all 
the new names you obtained white 
you were away into your 
SideKick data files 

ftcanafso: 

• Sort your address book by contact, 
zip code or company name 

• Print mailing labels 

• Print information selectively 

• Search files for existing addresses 
or calendar engagements 



Minimum system conf iguraHon: IBM PC, XT, AT, Portable, PCjr, 3270 and true 
256KRAM 



PC-DOS (MS-DOS) 2.0 or later. 



^K^jl^l^A SideKick and Traveling SideKick are registered trademarks and BinderWare Is a tradeniark of 

V^^B^Mm^B^ Borland International, Inc. IBM, AT, XT, and PCjr are registered trademarks of Internattonal 
INTERNATIONAL Business Machines Corp. MS-DOS IS a registered trademark Of Microsoft Corp. BOR0083 




The high-performance database manager 
thaVs so advanced iVs easy to use! 

Lets you organize, analyze and report information faster than ever before! If you manage mailing lists, 
customer files, or even your company's budgets— Reflex is the database manager for you! 

Reflex is the acclaimed, high-performance database manager you've been waiting for. Reflex extends 
database management with business graphics. Because a picture is often worth a 1000 words, Reflex 
lets you extract critical information buried in mountains of data. With Reflex, when you look, you see. 

The REPORT VIEW allows you to generate everything from mailing labels to sophisticated reports. 
You can use database files created with Reflex or transferred from Lotus 1-2-3,* dBASE* PFS: File,* 
and other applications. 




Reflex: the critics' choice 

. . if you use a PC, you should know about Reflex ... may be the best bargain in software today." 

Jerry Pournelle, BYTE 

"Everyone agrees that Reflex is the best-looking database they've ever seen." 

Adam B. Green, InfoWorld 

"The next generation of software has officially arrived." Peter Morton, PC Vllbek 

Reflex: don't use your PC without It! 

Join hundreds of thousands of enthusiastic Reflex users and experience the power and ease of use of 
Borland's award-winning Reflex. 

Suggested Retail Price $149.95 (not copy protected) 



tmnmrn system configuratioii: IBM PC. XT. AT. and true conqiatibles. 384K RAM minimum. IBM Celer BnpMes Adapter. Hercules 
Monoclurome Graphics CArd, or epMert. PC-DOS (MS-DOS) 2.0 or greater. Hard disk and mouse optional. Lotus 1-2-3. dBASE. 
or PFS: File optional. 

Reflex is a trademark of Borland/Analytica Inc. Lotus 1-2-3 is a registered trademark of Lotus 
Development Corporation. dBASE is a registered trademark of Ashton-Tate. PFS: File is a 
registered trademark of Software Publishing Corporation. IBM, XT, AT. and IBM Color Graphics 
^K^^B H J^ mBB^ Adapter are registered trademarks of International Business Machines Corporation. Hercules 

^9^0m9Mm^MWiW0 Graphics Card is a trademark of Hercules Computer Technology. MS-DOS is a registered 

INTERNATIONAL trademark of Microsoft Corp. BOR 0066B 

Copyright 1986 Borland International 



Includes 22 ''instant templates" covering a broad range of 
business applications (listed below). Also shows you how to 
customize databases, graphs, crosstabs, and reports. It's an invaluable 
analytical tool and an important addition to another one of 
our best sellers, Reflex: The Analyst 1.1. 

Fast-start tutorial examples: 

Learn Reflex® as you work with practical business applications. The Reflex Workshop Disk supplies 
databases and reports large enough to illustrate the power and variety of Reflex features. Instructions in each 
Reflex Workshop chapter take you through a step-by-step analysis of sample data. You then follow simple 
steps to adapt the files to your own needs. 

22 practical business applications: 

Workshop's 22 "instant templates" give you a wide range of analytical tools: 

Administration • Tracking Manufacturing Quality Assurance 

• Scheduling Appointments • Analyzing Product Costs 

• Planning Conference Facilities o-w csn^nni^i Dfo»«/n« 
. Managing a Project ^ iS^^^^^ " 

• Creating a Mailing System * Kio nrHorc 

• >^ Wopen. Applioa.«» ; ^^^^Tj^ 0,^ 
Sales and a/larloting * Analyzing Accounts Receivable 

• Researching Store Check Inventory • Maintaining Letters of Credit 

• Tracking Sales Leads • Reporting Business Expenses 

• Summarizing Sales Trends • Managing Debits and Credits 

• Analyzing Trends • Examining Leased Inventory Trends 

* Tracking Fixed Assets 

Production and Operations . planning Commercial Real Estate Investment 

• Summarizing Repair Turnaround 

Whether you're a newcomer learning Reflex basics or an experienced "power user" looking for tips, Reflex 
Workshop will help you quickly become an expert database analyst 



Minimum system configuration: IIM PC, AT, and XT, and true compatibles. PC-DOS (MS-DOS) 2.0 or greater. 384K RAM miiilmum. Requires Reflex: Tlie 
Analyst, and IBM Color Graphles Adapter, Hercules Monochrofflo Graphics Card or equivalent 




Suggested Retail Price: $69.95 
(not copy protected) 



Reflex is a registered trademark and Reflex Workshop is a trademark of Boriand/Anaiytica, Inc. IBM. AT, and XT are registered trademarks of International Business 
Mactiines Corp. Hercules is a trademark of Hercules Computer Technology. MS-DOS is a registered trademark of Microsoft Corp. 
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FOR THE MAC 



The easy-to-use relational database that thinks liiie a spreadsheet. 
Reflex for the tHlac lets you crunch numbers by entering formulas and linic 
databases by drawing on-screen lines. 

S free ready-to-use templates are Included on the examples disk: 



A sample 1040 tax application with Sched- 
ule A, Schedule B, and Schedule D, each 
contained in a separate report document. 
A portfolio analysis application with linked 
databases of stock purchases, sales, and 
dividend payments. 
A checkbook application. 




A client billing application set up for a law 
office, but easily customized by any 
professional who bills time. 
■ A parts explosion application that breaks 

down an object into its component parts 

for cost analysis. 



Reflex for the Mac accomplishes all of these tasks without programming— using 
spreadsiieet-like formulas. Some other Reflex for the Mac features are: 



Visual database design. 

"What you see is what you get" report and form layout 
with pictures. 

Automatic restructuring of database files when data 
types are changed, or fields are added and deleted. 
Display formats which include General, Decimal, 
Scientific, Dollars. Percent. 



Data types which include variable length text, number, 

integer, automatically incremented sequence number, 

date, time, and logipal. 

Up to 255 fields per record. 

Up to 16 files simultaneously open. 

Up to 16 Mac fonts and styles are selectable for 

individual fields and labels. 
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After opening the "Overview" window, you 
draw link lines between datat)ases directly 
onto your Macintosh screen. 



The link lines you draw establish both 
visual and electronic relationships between 
your databases. 



You can have multiple windows open 
simultaneously to view all members of a 
linked set— which are interactive and tnily 
relational. 



Critic's Choice 

"... a powerful relational database . . . uses a visual approach to information management." InfoWorld 

. . gives you a lot of freedom in report design; you can even import graphics." A+ Magazine 
". . . bridges the gap between the pretty programs and the power programs." Stewart Alsop, PC Letter 



BORLAND 

INTERNATIONAL 



Suggested Retail Price: $99.95* 

Introductory offer through 1-15-87 



MlHlanm SysfMi HB^Kfnmeate: 512K 

Reflex for the Mac is a trademark of Borland/Analytica, Inc. Macintosh is a trademark of Mcintosh Lat)oratory, Inc. and is used with express permission of its owner. 
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Increased Productivity for Anyone 
Using IBM^PCs or Compatibies 



SuperKey turns 1,000 keystrokes into 11 

Yes, SuperKey can record lengthy keystroke sequences and play them back at the touch of 
a single key. Instantly. Like magic. 

Say, for example, you want to add a column of figures in 1-2-3.* Without SuperKey, you'd 
have to type 5 keystrokes just to get started: @su m ( . With SuperKey, you can turn 
those 5 keystrokes into 1. 

SuperKey keeps your confidential fiies—CONFiDENTiAL! 

Time after time you've experienced it: anyone can walk up to your PC and read your 
confidential files (tax returns, business plans, customer lists, personal letters, etc.). 

With SuperKey you can encrypt any file, even while running another program. As long as 
you keep the password secret, only YOU can decode your file correctly. SuperKey also 
implements the U.S. government Data Encryption Standard (DES). 

SuperKey lieips protect yourcapitai investment 

SuperKey, at your convenience, will make your screen go blank after a predetermined time 
of screen/keyboard inactivity. You've paid hard-earned money for your PC. SuperKey will 
protect your monitor's precious phosphor and your investment. 

SuperKey protects your work from intruders wliiie you take a break 

Now you can lock your keyboard at any time. Prevent anyone from changing hours of 
work. Type in your secret password and everything comes back to life— just as you left it. 

Suggested Retaii Price: $69.95 (not copy protected) 

Minimum system configuration: IBM PC, XT, AT, PCjr, and true compatiblos. PC-OOS (MS-DOS) 2.0 or greater. 128K RAM. 
Ouo iMi driva. 




BORLAND 



INTERNATIONAL 



SuperKey is a registered trademark of Borland International, Inc. IBM. XT, AT, 
and PCjr are registered trademarks of International Business MacNnes Corp. 1-2-3 is a 
registered trademark of Lotus Devek)pment Corp. MS-DOS is a registered trademark of 
Microsoft Corp. 
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If you use an IBM® PC, you need 



U 




Turbo Lighining teams up 
with the Random Houso^ 
Concise Dictionary to 
ciiecis your speiiiog as 
you type! 

Turbo Ljghtning, using the 
83.000-worcl Random House 
Dictionary, checks your spelling 
as you type. If you misspell a 
word, it alerts you with a beep. 
At the touch of a key. Turbo 
Lightning opens a window on 
top of your application pro- 
gram and suggests the correct 
spelling. Just press one key 
and the misspelled word is 
instantly replaced with the 
correct word. It's that easy! 

Turbo Ligiitning worics 
iiand'in-baoi with the 
Random House Thesaurus 
to g 'm you instant access 
to synonyms 

Turbo Lightning lets you choose 
just the right word from a list of 
alternates, so you don't say the 
same thing the same way every 
time. Once Turbo Lightning 
opens the Thesaurus window, 
you see a list of alternate 
words, organized by parts of 
speech. You just select the 
word you want, press ENTER 
and your new word will in- 
stantly replace the original 
word Pure magic! 



if you em write a 
word, thinic a wordi or 
say a word, you need 
Turbo Lightning 




.i.ri Jjs i/e^iwi 
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The Turbo Lightning Dictionary 




The Turbo Lightning Thesaurus 



Suggested Retail Price: t99M (not copyprotected) 



Turbo Lightning's 
inteiiigence iets you teach 
it new words. The more 
you use Turbo Lightning, 
the smarter it gets 

You can also teach your new 
Turbo Lightning your name, 
business associates' names, 
street names, addresses, 
correct capitalizations, and any 
specialized words you use 
frequently. Teach Turbo 
Lightning once, and It 
knows forever. 

Turbn Lightning 
is the engine that 
powers Borland's Turbo 
Lightning Library 

Turbo Lightning brings 
electronic power to the Random 
House Dictionary and Random 
House Thesaurus. They're at 
your fingertips— even while 
you're running other programs. 
Turbo Lightning will also 
"drive" soon-to-be-released 
encyclopedias, extended 
thesauruses. specialized 
dictionaries, and many other 
popular reference works. 
You get a head start with this 
first volume in the Turbo 
Lightning Library. 

And because Turbo Lightning is 
a Borland product, you know 
you can rely on our quality, our 
60-day money-back guarantee, 
and our eminently fair prices! 



MiRimimi system configuration: IBM PC, XT, AT, PCjr, and tnia 
25«( RAM. Hard disir reconHnentfed. 



with 2 floppy disk drives. PC-DOS (MS-DOS) 2.0 « greater. 




IBM; XT, AT, and PCjr are registered trademarks of International Business Mactiines Corp. Turbo 
Ughtning is a registered trademarl( and Turbo Ugtitning Library is a trademark of Borland 
International, Inc. Random House is a registered trademark of Random House Inc. bor oo7QA 



Your Development Toolbox and Technical Reference Manual for Hirbo lightning* 



LIGHTNING 



Lightning Word Wizard inciudes compiete, commented Turbo 
Paseai® source code and ali ttie teclinical information you'ii 
need to understand and mrk witti Turbo Lightning's "engine" 

More than 20 fuiiy documented Turbo Pascai procedures 
reveai powerfui Turbo Lightning engine caiis. Harness the fuii power 
of the compiete and authoritative Random House® Concise 
Word List and Random House Thesaurus. 



Turbo Ligtitning's "Reference 
Manual" 

Developers can use the versatile on-line 
exanfiples to harness Turbo Lightning's 
power to do rapid word searches. Lightning 
Word Wizard is the forerunner of the data- 
base access systems that will incorporate 
and engineer the Turbo Lightning Library" 
of electronic reference works. 



The ultimate collection of word 
games and crossword solvers! 

The excitennent, challenge, competition, 
and education of four games and three 
solver utilities— puzzles, scrambles, spell- 
searches, synonym-seekings, hidden words, 
crossword solutions, and more. You and 
your friends (up to four people total) can 
set the difficulty level and contest the high- 
speed smarts of Lightning Word Wizard! 



Turbo Lightning— Critics' Choice 

"Lightning's good enough to make programmers and users cheer, executives of other 
software companies weep." Jim Seymour, PC Weeic 

"The real future of Lightning clearly lies not with the spelling checker and thesaurus currently 
included, but with other uses of its powerful look-up engine." Ted Silveira, Profiles 



"This newest product from Borland has it all." 



Don Roy, Computing Now! 



1 system configuration: IBM PC. XT, AT. PCjr. Portable, and true compatibles. 256K RAM minimum. PC-OOS (MS-DOS) 2.0 
or greater. Turbo Liglitning software required. Optional— Turbo Pascal 3.0 or greater to edit and compile Turbo Pascal source code. 



INTERNA T I 0 N A L 



Suggested Retail Price: $69.95 
(not copy protected) 



Turbo Pascal and Turbo Lightning are registered trademarks and Liglitning Word Wizard and Turbo Ligt^tning Library are trademarks of Borland Internatiortal, Inc. Random 
House is a registered trademark of Random House, Inc. IBM, XT, AT, and PCjr are registered trademarks of International Business Machines Corp. MS-DOS is a 
registered trademark of Microsoft Corp. boroo87A 



TUSBdRASCAL 

VERSION 3.0 with 8087 support and BCD reals 

Free MicroCalc Spreadsheet With Commented Source Code! 



FEATURES: 

One-Step Compile: No hunting & fishing 
expeditions! Turbo finds the errors, takes you 
to them, lets you correct them, and instantly 
recompiles. You're off and running in 
record time. 

Built-in Interactive Editor: WordStars-like 
easy editing lets you debug quickly. 

Automatic Overlays: Fits big programs into 
small amounts of memory. 

NllcroCaic: A sample spreadsheet on your disk 
with ready-to-compile source code. 

fflAT PC Version: Supports Turtle Graphics, 
color, sound, full tree directories, window 
routines, input/output redirection, and 
much more. 



THE CRITICS' CHOICE: 

"Language deal of the century . . . Turbo Pascal: 
it introduces a new programming environment 
and runs like magic." 

—Jell Duntemaon, PC Magazine 

"Most Pascal compilers barely fit on a disk, but 
Turbo Pascal packs an editor, compiler, linker, 
and run-time library into just 39K bytes of 
random access memory." 

—Dave Garland, Popular Computing 

"What I think the computer industry is headed 
for: well-documented, standard, plenty of 
good features, and a reasonable price." 

-^erry Poumelle, BYTE 



LOOK AT TURBO NOWl 



\3f More than 500.000 users worldwide. 

Turbo Pascal is the de facto industry 
standard. 

\3f Turbo Pascal wins PC MAGAZINE'S 
award for technical excellence. 



Turbo Pascal named "Most 
Significant Product of the Year" by 
PC WEEK. 

Of Turbo Pascal 3.0— the fastest Pascal 
development environment on the 
planet, period. 



Suggested Retail Price: $99.95; CP/M^-SO version without 8087 and BCD: $89.95 

Features lor IS-bit Systems: 8087 math co-processor support for intensive calculations. 
Binary Coded Decimals (BCD): eliminates round-off error! A must for any serious business application. 



I system configiifation: 128K RAM minimum. iMludes 8087 & BCD features for 16-blt IMS-DOS 2.0 orlaler and 
CP/M-86 1.1 or later. CP/M-80 version 2.2 or later 48K RAM minimum (8087 and BCD features not avaHabte). 8087 
version requires 8087 or 80287 co-processor. 



^^M^^^^^ ■ft^i^B^B M, WLMW^ Turbo Pascal is a registered badeinark of BoMb^^ 

g— ^ ^^^^M ^S^^PIK^^vAl^^^^ oivoi Kesearcn inc. idm is a reoisiereQ laaenBnc or RwernaDoiiai Business Macnmes corp. ms- 
^s^^^^W ^ ^ T ^^TtT T?^^ OOSIsaregjsteredtradernarkofMjcro80llCffp.WlDfilSlarisaie9 
I n f t H N A J I 0 N A L (ntemaiional 

BOR0061A 



WRBOOiSCAL 

TURBOTUTGR 

VERSION 2.0 

Learn Pascal From The Folks Who Created 
The Turbo Pascal® Family 

Borland International proudly presents Turbo Tutor, the perfect complement 
to your Turbo Pascal compiler. Turbo Tutor Is really for everyone— 
even If you've never programmed before. 

And if you're already proficient, Turbo Tutor can sharpen up the fine points. 
The manual and program disk focus on the whole spectrum of Turbo 
Pascal programming techniques. 

• For the Novice: It gives you a concise history of Pascal, tells you how to write a 
simple program, and defines the basic programming terms you need to know. 

• Programmer's Guide: The heart of Turbo Pascal. The manual covers the fine points 
of every aspect of Turbo Pascal programming: program structure, data types, control 
structures, procedures and functions, scalar types, arrays, strings, pointers, sets, files, 
and records. 

• Advanced Concepts: If you're an expert, you'll love the sections detailing such topics as 
linked lists, trees, and graphs. You'll also find sample program examples for PC-DOS and 
MS-DOS.* 

10,000 lines of commented source code, demonstrations of 20 Turbo Pascal features, multiple- 
choice quizzes, an interactive on-line tutor, and more! 

Turbo Tutor may be the only reference work about Pascal and programming you'll ever need! 
Suggested Retail Price: $39.95 (not copyprotected) 

Minimum system configuration: Turbo Pascal 3.0. PC-DOS (MS-DOS) 2.0 or later. 192K RAM minimum (CP/M-80 
version 2.2 or later: 64K RAM minimum). 



■^^^■^■■^•■^■^ Turbo Pascal and Turbo Tutor are registered trademarks of Borland Intemabonal Inc. CP/M Is a registered 
INTERNATIONAL tradernark of Digital Research Inc. MS-DOS is a registered trademarl( of Mk^osoft Coq^^ boroo64B 



DxeabaseToolbox' 

Is The Perfect Complement To Turbo Pascal" 

It contains a complete library of Pascal procedures that 
allows you to sort and search your data and build powerful database 
applications. It's another set of tools from Borland that will give 
even the beginning programmer the expert's edge. 

THE TOOLS YOU NEED! 
TURBO ACCESS Using B+ trees: The best way to organize and search your data. Makes it 
possible to access records in a file using key words instead of numbers. Now available with 
complete source code on disk, ready to be included in your programs. 

TURBO SORT: The fastest way to sort data using the QUICKSORT algorithm— the method 
preferred by knowledgeable professionals. Includes source code. 

GINST (General IttstallaUott Program): Gets your programs up and running on other 
terminals. This feature alone will save hours of work and research. Adds tremendous value 
to all your programs. 

GET STARTED RIGHT AWAY— FREE DATABASE! 

Included on every Toolbox diskette is the source code to a working database which 
demonstrates the power and simplicity of our Turbo Access search system. Modify it to suit 
your individual needs or just compile it and run. 

THE CRITICS' CHOICE! 

'The tools include a B+ tree search and a sorting system. I've seen stuff like this, but not as 
well thought out, sell for hundreds of dollars.'* —Jerry Poumell, BYTE MAGAZINE 

"The Turbo Database Toolbox is solid enough and useful enough to come recommended." 

—Jeff Duntemann, PC TECH JOURNAL 



Suggested Retail Price: $69.95 (not copyprotected) 



Minimum system configuration: 128K RAM and one disic drive (CP/M-80: 48K). 16-bit systems: Turbo 
Pascal 2.0 or greater for MS-DOS or PC-DOS 2.0 or greater. Turbo Pascal 2.1 or greater for CP/M-86 
1 .0 or greater. 8-bit systems: Turbo Pascal 2.0 or greater for CP/M-80 2.2 or greater. 




Turbo Pascal and Turbo Database Toolbox are registered trademarks of Borland International 
Inc. CP/M is a registered trademark of Diglal Researcli, Inc. MS-DOS is a registered 



EduorToolbok 

irs All You Need To Build Your Own Text Editor 
Or Word Processor 



Build your own Ughtning-fast editor and incor- 
porate it into your Turbo Pascal^ programs. 

Turbo Editor Toolbox gives you easy-to-install 
modules. Now you can integrate a fast and powerful 
editor into your own programs. You get the source 
code, the manual, and the know-how. 



Create your own word processor. We provide all 
the editing routines. You plug in the features you want. 
You could build a WordStar*-like editor with pull-down 
menus like Microsoft's* Word, and make it work as fast 
as WordPerfect.* 



To demonstrate tiie tremendous power of Turbo Editor Toolbox, we give you tbe source code for 
two sample editors: 

Simple Editor A complete editor ready to include in your programs. With windows, block commands, and 

memory-mapped screen routines. 
fi/iicroStar A full-blown text editor with a complete pull-down menu user interface, plus a lot more. 

Modify MicroStar's pull-down menu system and include it in your Turbo Pascal programs. 

Tfie Turbo Editor Toolbox gives you all the 
standard features you would expect to find 
in any word processor: 

• Wordwrap 

• UN-delete last line 

• Auto-indent 

• Find and Find/Replace with options 

• Set left and right margin 

• Block mark, move, and copy 

• Tab, insert and overstrike modes, 
centering, etc. MicroStar's pull-down menus. 




And Turbo Editor Toolbox has features that word processors selling for several hundred dollars can't begin to match. 
Just to name a few: 



0^ RAIi/l'based editor. You can edit very large 
files and yet editing is lightning fast. 
Memory-mapped screen routines. In- 
stant paging, scrolling, and text display. 
Keyboard installation. Change control 
keys from WordStar-like commands to any that 
you prefer. 



Multiple windows. See and edit up to eight 
documents— or up to eight parts of the same 
document— all at the same time. 
0^ Multitaslcing. Automatically save your 
text. Plug in a digital clock, an appointment 
alarm— see how it's done with MicroStar's 
"background" printing. 



Best of all, source code is included for everything In the Editor Toolbox. 
Suggested Retail Price: $69.95 (not copy protected) 

Minimum system configuration: IBM PC, XT, AT, 3270, PCjr, and true compatibles. PC-DOS (MS-DOS) 2.0 or greater. 192K RAM. You must be 
using Turbo Pascal 3.0 for IBM and compatibles. 



INTERNATIONAL 



Turbo Pascal is a registered trademark and Turbo Editor Toolbox is a trademark of Borland 
International. Inc. WordStar is a registered trademark of MicroPro International Corp. Word and 
MS-DOS are registered trademarks of Microsoft Corp. WordPerfect is a trademark of Satellite 
Software International. IBM, XT, AT. and PCjr are registered trademarks of International Business 
Macfiines Corp. BOR 0067A 



TUBBOnkSnAL 

GOMElVbRKS 

Secrets And Strategies Of The Masters Are 
Revealed For The First Time 

Explore the world of state-of-the-art computer games with Turbo GameWorks. Using 
easy-to-understand examples, Turbo GameWorks teaches you techniques to quickly create 
your own computer games using Turbo Pascal.* Or, for instant excitement, play the three 
great computer games we've included on disk^compiled and ready to run. 

TURBO CHESS 

Test your chess-playing skills against your computer challenger. With Turbo GameWorks. you're on your way to 
becoming a master chess player. Explore the complete Turbo Pascal source code and discover the secrets of 
Turbo Chess. 

"What impressed me the most was the fact that with this program you can become a computer chess analyst. 
You can add new variations to the program at any time and make the program play stronger and stronger chess. 
There's no limit to the fun and enjoyment of playing Turbo GameWorks Chess, and most important of all, with this 
chess program there's no limit to how it can help you improve your game." 

—George KolianoMifski, Ifean of American Chess, former President of 
tfie United Chess Federation, and syndicated chess columnist 

TURBO BRIDGE 

Now play the world's most popular card game— bridge. Play one-on-one with your computer or against up to 
three other opponents. With Turbo Pascal source code, you can even program your own bidding or scoring 
conventions. 

"There has never been a bridge program written which plays at the expert level, and the ambitious user will 
enjoy tackling that challenge, with the format already structured in the program. And for the inexperienced player, 
the bridge program provides an easy-to-follow format that allows the user to start right out playing. The user can 
'play bridge' against real competition without having to gather three other people." 

—Kit Woolsey, writer of several articles and hooks on hridge, 
and twice champion of the Blue Rlhhon Pairs. 

TURBO GO'MOKU 

Prepare for battle when you challenge your computer to a game of Go-Moku— the exciting strategy game also 
known as Pente* In this battle of wits, you and the computer take turns placing X's and O's on a grid of 19X19 
squares until five pieces are lined up in a row. Vary the game if you like, using the source code available on your 
disk. 

Suggested Retail Price: $69.95 (not copy protected) 

fmmm systm coiriigiratim: IBM PC, XT, AT. Portable. 3270. PCjr, and true compatibles. PC-DOS (MS-DOS) 2.0 or later. 1S2K 
RMI iiihihnam. To edit and comple Ibe Turbo Pascal soyree code, you must be using Turbo Pascal 3.0 for IBM PCs and 




M^^I^P^M Jjb |^n|% 'Turbo Pascal and Turbo GameWorks are registered trademarks of Borland Internatiorial, Inc. 
IB^^ICLp^IVI^ ^^"^^ ^ registered trademark of Parker Brottiers. IBM, XT, AT, and PCjr are registered 
INTERNATIONAL tradernarks Of International Business Machines Corporation. MS-DOS is a registered tradeniark 
of Microsoft Corporation. 



BOR 0065B 



GRAPHIXTOOLBOK' 

AUbnry of Gmphics Routines for Use with Turbo Pascai^ 

High-resolution grapliics for your IBNI® PC, AT,^ XT,® PCjr®, true PC compatibles, and the Heath 
Zenith Z-IOO." Comes complete with graphics window management 

Even if you're new to Turbo Pascal programming, the Turbo Pascal Graphix Toolbox will get you started 
right away. It's a collection of tools that will get you right into the fascinating world of high-resolution 
business graphics, including graphics window management. You get immediate, satisfying results. And 
we keep Royalty out of American business because you don't pay any— even if you distribute your own 
compiled programs that include all or part of the Turbo Pascal Graphix Toolbox procedures. 





What you get includes: 



Complete commented source code on disk. 
Tools for drawing simple graphics. 
Tools for drawing complex graphics, including 
curves with optional smoothing. 
Routines that let you store and restore 
graphic images to and from disk. 
Tools allowing you to send screen images to 
Epson-compatible printers. 



Full graphics window management. 
Two different font styles for graphic labeling. 
Choice of line-drawing styles. 
Routines that will let you quickly plot 
functions and model experimental data. 
And much, much more . . . 



"While most people only talk about low-cost persona! computer software, Borland has been doing 
something about it. And Borland provides good technical support as part of the price." 

John Markov & Paul Freiberger, syndicated columnists. 

if you ever plan to create Turbo Pascal programs that make use of business graphics or scientific 
graphics, you need the Turbo Pascal Graphix Toolbox. 

Suggested Retail Price: $69.95 (not copy protected) 

Minimum system configuration: IBM PC, XT. AT, PCjr, true compatiiries and the Heath Zenith Z-100. Turbo Pascal 3.0 or later. 192K RAM 
minimum. Two disk drives and an IBM Color Graphics Adapter (CGA), IBM Enhanced Graphics Adapter (EGA), Hercules Graphics Card or 



E R N A 



Turbo Pascal and Turbo Graphix Toolbox are registered trademarks of Borland International, Inc. 
IBM, XT, AT, and PCjr are registered trademarks of International Business Macftines Corporation. 
Hercules Graphics Card is a trademark of Hercules Computer Tecti. Heath Zenith Z-100 is a 
trademark of Zenith Data Systems. bor oo68A 



PROlOG 

the fKrturd language of Artifiddlnitieige^ 

Turbo Prolog brings fifth-generation supercomputer 
power to your IBM^PCl 



urbo Prolog takes 
rogramming into a new, 
atural, and logical 
nvironment 

nth Turbo Prolog, 

ecause of its natural, 
igical approach, both 
Bople new to programming 
id professional programmers 
an build powerful applica- 
Dns such as expert systems, 
jstomized knowledge 
ases, natural language 
terfaces, and smart 
formation management systems. 

urbo Prolog is a declarative language 
hich uses deductive reasoning to solve 
rogramming problems. 



Turbo Prolog's development system 
includes: 

□ A complete Prolog compiler that is a variation 
of the Ciocksin and Mellish Edinburgh 
standard Prolog. 

□ A full-screen interactive editor. 

□ Support for both graphic and text windows. 

□ All the tools that let you build your own 
expert systems and Al applications with 
unprecedented ease. 



Turbo Prolog provides 
a fully integrated pro- 
gramming environment 
like Borland's Turbo 
Pascal,® the de facto 
worldwide standard. 

You get the 
complete Turbo 
Prolog program- 
ming system 

You get the 200-page 
manual you're holding, 
software that includes 
the lightning-fast Turbo 
Prolog six-pass 
compiler and interactive editor, and the 
free GeoBase natural query language 
database, which includes commented 
source code on disk, ready to compile. 
(GeoBase is a complete database designed 
and developed around U.S. geography. 
You can modify it or use it "as is.") 

MMmum system configuration: iBM PC, XT, AT, Portable, 3270, PCjr 
and true compattbles. PC-DOS (iMS-DOS) ^0 or iater. 384K RAM 



Suggested Retail Price $99.95 
(not copy protected) 





"W ' INTERNAtlONAL 



Tufto Prolog is a Irademaik and Turto Pascal Is a registered trademark of Bortand Hemational, Inc. 
IBM. AT, XT, and PCjr are registered trademarks ol International Business Machines Corp. MS-OOS Is a 
tegislHed tradenak of Microsolt Corp. „ 

BOR 0016C 
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BORLANV^ 

INTERNATIONAL ] 



To Order ^ 
By Credit j 
Carcf, % 

(800) 




60 DAY 
MONEY-BACK 
6UARANTEE 





m California z 
^ call I 

(800) f 
742-1/35 




The ultimate 
Pascal development 
environment 




B 



orland's new Turbo Pascal for the Mac is so incredibly 
fast that it can compile 1,420 lines of source code in 
the 7.1 seconds it took you to read thisi 



And reading the rest of this takes 
about 5 minutes, which is plenty of 
time for Turbo Pascal for the Mac to 
compile at least 60,000 more lines 
of source code! 

Turbo Pascal for the Mac does 
both Windows and "Units" 

The separate compilation of routines 
offered by Turbo Pascal for the Mac 
creates modules called "Units," which 
can be linked to any Turbo Pascal* 
program. This "modular pathway" 
gives you "pieces" which can then be 
integrated into larger programs. You 
get a more efficient use of memory 
and a reduction in the time it takes 
to develop large programs. 

Turbo Pascal for the Mac Is 
so compatible with Lisa'' that 
they should be living together 

Routines from Macintosh Program- 
mer's Workshop Pascal and Inside 
Macintosh can be compiled and run 
with only the subtlest changes. Turbo 
Pascal for the Mac is also compatible 
with the Hierarchical File System of 
the Macintosh ™ 



3 MacWinners from Borland! 

First there was SideKick for the Mac," 
then Reflex for tfie Mac.™ and now 
Turbo Pascal for the Mac"! 



The 27-second Guide to 
Turbo Pascal for the Mac 

Compilation speed of more than 
12.000 lines per minute 
"Unit" structure lets you create 
programs in modular form 
Multiple editing windows— up 
to 8 at once 
of Compilation options include 
compiling to disk or memory, 
or compile and run 
No need to switch between 
programs to compile or run a 
program 

Streamlined development and 
debugging 

Compatibility with Macintosh 
Programmer's Workshop Pascal 
(with minimal changes) 
Compatibility with Hierarchical 
File System of your Mac 
Ability to define default volume 
and folder names used in 
compiler directives 
Search and change features in 
the editor speed up and 
simplify alteration of routines 
Ability to use all available 
Macintosh memory without limit 
"Units" included to call all the 
routines provided by Macintosh 
Toolbox 



Minimum system configuration: 256K One 400K drive 

Turbo Pascal is a registered trademark and Turbo Pascal for the Mac, SideKick for the Mac. and Reflex for the Mac are 
trademarks of Borland International, Inc. Macintosh is a trademark of Mcintosh Laboratories, Inc. and licensed to Apple 
Computer with its express permission. Lisa is a registered trademark of Apple Computer. Inc. Inside Macintosh is a 
copyright of Apple Computer, Inc. Copyright 1986 Borland International BOR oi67A 



INTERNATIONAL 



4585 SCOTTS VALLEY DRIVE 
scons VALLEY, CA 95066 
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